Let’s talk about documentation.
Why is it necessary?
Who is it for?
What purpose does it serve?
Is it meant to be a snapshot, a static signed-off deliverable, or a living document?
What level of detail does it need to be to serve its purpose well?
Who’s the right person to write such a document?
Is it complete, or does it need to be supplemented by accompanying material?
Who should keep it up to date (if at all)?
If it is out of date, should it be archived, and replaced with something else?
Is it easily accessible for those who need to see it?
A lot of people hate doing documentation; it is a chore to be borne with distaste.
I love it, because it is a medium to communicate –
– the vision
– what the customer wants
– how we are going to build it
– what we’ve built
– why decisions were made
– how the system can be used properly
– who needs to read it to benefit
– why we’ve done what we’ve done in the way we’ve done it
I’ve heard grumblings where people have been asked to write documentation which no one will read.
It’s true, I know it happens.
In my projects I always try to make sure that all the documentation is written properly for the right audience. I abhor documentation for the sake of documentation.
Inaccurate and out of date documentation is just as bad as no documentation at all, so we need to strike a balance.
During the life of a project (and beyond), all system updates and changes need to be documented in a logical, structured manner – preferably with an audit trail of decisions that have been taken to shape it.
Otherwise, you won’t know why it does the things it does, and you will have challenges trying to troubleshoot or extend it when the need arises.
Like many things, I can probably talk about documentation until the 🐄 come home, but when I get a text like the one below, I have this 🐝 in my bonnet that I just have to release or I will explode.
#Documentation.
Do it right.
#OnThePeiroll
#ProjectManagement
