It’s time for the standard disclaimer again! This article, as with all in this series, is based upon personal experiences and from experiences of other people I have spoken to. What I write here is my opinion and my personal thoughts regarding how to get the best out of each of the project phases – none of it is reflective of the views of my employer.
I should also make very clear that any people or companies I write about here are not real but are fictitious composites made up of conversations that we’ve all had, with characters we’ve all met at some point.
Is that a light at the end of the tunnel, or is it merely a man with a flamethrower heading towards me? I actually think that we might be approaching the fun part of the project!
It honestly seems like we were in the last ice age when I started this project, but I can sense that the development phase is definitely within touching distance.
The only thing that stands between me and the fun of dev work, is documentation… oh, how I HATE documentation.
Here at Oak & Stag Engineering the documentation phase firmly sits with the developers. Sven produced the initial outline and systems design, and Limahl (quite possibly THAT one) produced the licensing costs sheet, but it is now over to me to write the “Function User Design Guide Exposition”.
The FUDGE is the detailed document outlining everything from the name of the little tick box that indicates that Primrose in Potential Purchases has met the person, to the very specific colour of the header bar when the account has spent over £50 with us.
It also includes all the required information for Kane and Annabel in Information Security Oversight, Legislation and Technical Enforcement (ISOLATE) to be able to review and, if you have performed all the rituals and ceremonies, given their seal of permission to continue.
Once that is done, I then have to produce the System Information Mapping Process LEvel Specification (SIMPLES) document detailing all of the dot-to-dot work needed to move all of the data we need from the old system to the shiny new cloud.
The first challenge in compiling the FUDGE and the SIMPLES is locating the latest template to use. This is all dependent upon who you really need to get on board as each individual signatory will have their own “company standard” version of the document, and if you don’t use their version then you can face a lengthy rewrite.
It’s even more complicated when, like me, you need to use the ISOLATE template as these change every week to cater for every single event that hits the news – from North Korea playing toy soldiers to The Donald insisting that all companies doing business in the US must comply with Covfefe standards.
This isn’t getting on with it, is it? Prevarication in documentation is something we really should start allowing for in project plans!
This template is the work of a twisted mind, with more sections than Word can comprehend and more Appendices than the NHS can remove, but needs must.
Many, many, MANY, cups of coffee later….
It’s done! I’ve actually managed to navigate the maze of impossible options and produce a FUDGE that is as streamlined as possible. I’m rather proud to say that it only has 347 pages and 76,432 words!
Trust me, that’s a lightweight document!
It’s been handed over to the ISOLATE pair, 8 times, and finally received their signature which left me with only one thing to do before commencing work on building this new nirvana – and that’s writing the SIMPLES!
Have you ever made string art? You know, the thing where you have a load of pins on a board and you wrap loads of coloured string around them to make pretty pictures and patterns.
Well, my data map looked as though Chaz and Wilbur had attempted to do one of these after one of their epic pub crawl sessions! It wasn’t string art, as much as string chaos.
With the mass of data being migrated from our old system the data map was always going to be a challenge to draw up, but I really didn’t expect a Jackson Pollock clone.
As I looked back on the sessions with Belinda and Andy, the Blue-Sky Capability Co-ordinators, I managed to piece together enough of a picture of the data that we actually needed which meant that we would be migrating only 70% of the current database size.
Most importantly though was the fact that Patty, Pete, and Primrose from Potential Purchases would still be getting the details that they needed about Mrs Sneflingtons letter from 1979.
I just need to ensure that the double-back-flip somersault whilst performing a 720 twist and juggling 4 chainsaws all simultaneously doesn’t fall over, or we might end up with some very interesting data results!
But it’s all GOOD NEWS! I can FINALLY move on to doing the fun stuff – the development!
I’ve never worked in an IT department where that has been as popular as microwaving kippers in the communal kitchen, and then eating them at your desk whilst airing your feet after doing a 5Km run during your break.
It’s one thing that we all acknowledge that we need, but none of us seems to want to do. It’s also the one thing that you have got to have for the project to be a measurable success.
Each organisation has its own ideas of what documentation is required, and this often depends on the departmental structure as well as the business sector you are working in.
Then there’s the project methodology that the organisation is using – this can have a major impact on what needs to be documented, and just how many documents are needed.
A “typical” scenario would be where the business analysts provide an analysis of the current and future states, the solution architect produces a design document covering the overall architecture, and the developer produces a technical design/specification document with the nuts and bolts within.
It may also be up to the developer to design the Data Migration Process and with it all of the data mapping.
All of this documentation, along with the overarching project documents, are crucial for ensuring that you know what you are expected to deliver, the platform you are building it on, and how you are actually going to build and deliver it.
Sometimes these documents can end up being merged together, but the core elements of the individual docs still remain.
When writing the documents a key factor is ensuring that you have a clear idea of the sections and structure of the document before you begin. This can sometimes already be defined, but often evolves with each project and you can be pretty sure that you will have sections that need to be added, along with some that aren’t relevant and need to be removed.
Making these readable can be a huge challenge. It’s easy to forget that not everyone knows their CDS from their SQL and that some acronyms will mean different things to different people.
With that in mind, I always ensure that a glossary of terms and acronyms is right at the beginning of the document – somewhere the reader cannot miss it, and doesn’t require them flipping to the back before they can understand what is written in the introduction!
Something as simple as that can make a massive difference to the way your documentation will be received. If it’s easy to read, and well laid out, then the length of the document won’t matter.
A well-written document of 100+ pages will be more welcomed than a 50-page document of acronyms, jargon, and poor structure – trust me, I’ve written both!
The Data Migration/Mapping document is invaluable, especially if you are not taking all the data across and if you are not recreating the new system as a like-for-like.
Knowing that the data from the Company Area field on the account entity is to go to the new Region field on the Account entity is pretty fundamental information to have listed.
But it’s also about knowing what filters you are putting on the data, and just how that cascades down the chain.
If you are only migrating Accounts with activity in the last 24 months, what does that mean to the historical data and how does that impact any connected accounts, contacts, activities, cases etc.
Having all of this documented, and then agreed, can be the biggest help as you get into the nitty-gritty of building all of this.
It’s not about having a CYA (cover your ass) policy, and it’s not about saying “nope, not in the spec”, but it’s about ensuring that all parties know what is being delivered and what is being left behind.
And at the end of the day, that is the key with all documentation – it’s all about ensuring that the information is communicated and understood by all the relevant people and that people, later on, will be able to pick up the docs and understand the rationale behind the actions that you have taken.
The good thing is that once you’ve overcome this hurdle, you are normally good to get on with the fun stuff – the customisation, configuration and building.