The Benefit of Documentation When Implementing New Databases

 

So: If you're reading this blog post and wondering why I am even bothering to write it - because of course documentation is important - then great! You can stop reading now! Go and have a laugh at today's Dilbert instead. But if you do doubt the benefit of documentation in database implementations (or if you like the sound of documentation lite…) then read on… Because this is why I think documentation is important:

• Structure for project managers: It gives the people running the project structure - it helps them see what's what, where we are, what we are doing, who's doing it, what needs to be done and so on. I know these are easy words to write and perhaps not tight enough (especially for a blog about documentation!) but this is the heart of the benefits which documentation brings. As a project manager it gives me what I need.
• Structure and assurance for project boards: Following on from the above point, it gives your project board the same assurance and support.
• Accountability: This is important. It means that we have a written record as to what was discussed, decided, agreed (or not), for who, by when and so on. It's especially useful for when disagreements arise between a supplier and client, as we can then have at least a starting point to discuss.
• Blueprints: For projects which do require some up-front consideration of how the database is going to be configured, especially where a third-party supplier is doing that work, blueprints are pretty much essential. This is what was decided by client and supplier, this is what the supplier will deliver, and this will help formalise the project and avoid (a set of) arguments later about this.
• Data dictionaries: I wrote a blog recently about the benefit of data dictionaries - I still believe all that.
• If someone leaves… I've been brought into projects where an organisation is half way through a database implementation and I have needed to catch-up quickly with where they are. The better the documentation - i.e. the more poignant it is, not necessarily the amount of it - the better it is for someone new to be able to get up to speed.
• Agile methodology: I know some Agile evangelists believe that documentation is not so helpful because things can change so quickly in the next sprint anyway. I guess this is something that every Agile implementation needs to consider: is there some space and reason to have relevant documentation? Or do we agree it's not necessary. It might worry me sometimes…
• The more attentive of you will have realised that much of what I am promoting is to do with "clients and suppliers". Yes, that's true. I do think this is where documentation can help. It keeps everyone on track, maintains a level, fair playing field for both parties and I think instils good practise in implementations.

Then of course there are project plans, risk registers, communication strategies, data mapping tables, file formats for data integration and so on. I realise that even fans of documentation lite might see these types of documentation as more useful, but that doesn't always seem to be the case in my experience. Personally, I think we need them.

And just to finish with a couple of caveats: Documentation does not have to mean wreathes of paper - a well structured, online system of "documentation" can be just as useful for many of these issues. As long as it is structured, searchable, auditable, accessible then great, I'm all for that. And I am not saying that you need to follow PRINCE2 to the letter and create Product Descriptions to the nth degree - i.e. I'm not saying you should have documentation for documentation's sake. I realise there are times when keeping documentation to a minimum - or rather, to the amount appropriate for your organisation and your implementation - is right. But I still think documentation is needed.