Documentation: The Murder Book
Fans of crime novels know that members of a murder investigation team are obliged to write down everything that they learn about the case. The collection of such documents is known as the murder book.
This book contains things like: photographs of the crime scene, interview notes, witnesses’ statements, forensic reports, autopsy reports, sketches and diagrams that provide additional understanding, documentary evidence like invoices and phone bills, copies of birth and death certificates…….and any other documents that potentially provide more insight into the case. The intention of the book is to provide a chronological paper trail of the murder investigation from the time that the murder is first reported to the time that it is solved.
Regardless of the techniques used for the investigation the investigators are obligated to take the time to regularly add all their new knowledge to the murder book. Picture the scene when the detective, having spent the day interviewing suspects and following leads, makes his weary way back to his desk to finish the paper work for the day. He’s tired, he wants to go home take off his shoes and mix himself a martini – but first he has to make sure that he captures what he has learned before he forgets it. Without exception, the murder book must be kept up to date so that everyone has access to a common understanding of the story so far. And the investigators often go back over parts of the murder book and use it to refresh their memories and to gain fresh insights into new developments.
People working in the world of organisational, software and hardware systems also need a complete trail of the story of the system so far. During the lifetime of any system there is often a need to make some kind of change. The change might affect the organisation, hardware, software or anything in the world surrounding the system. The change might be to fix something that does not work, to add some new functionality or to make improvements by changing technology. Whatever the reason for the change, before making it, the changers need to understand what is there already. They need to understand the potential effects of the change so that they can choose the best alternative. At this point people would benefit from accurate documentation but often to find that there is none and the people who built the original system have left the organisation.
When you ask “why is there no documentation?”, the most common reason is – “there was no time to produce it, we had a very tight deadline and when the project finished we went straight on to another one”. So why is it that the murder investigators who are invariably under extreme pressure manage to produce useful documentation while it is such a rarity in systems engineering?
Here’s the difference: the investigators produce the murder book as part of the work of investigating the murder – and they do it progressively. On the first day of the case they start the book by writing the notes for that day and tagging any additional documents with that date. As they progress through the investigation each of the members of the investigation team adds more notes, including date and name of investigator, to the book. The murder book is built progressively, by the whole team, as a result of doing the work. And everyone on the team values the murder book and uses it to help them with the investigation.
In systems engineering projects documentation is thought of as something that you do at the end of the project – when the new system has been installed. This does not work because, even if you have time at the end of the project, you won’t remember all the juicy (or more importantly the relevant) details. So the documentation might look nice but it does not reflect the reality of the system.
We could borrow the idea of the murder book and start documentation as soon as we start any project. But to make this work successfully a couple of things need to be in place. Firstly each member of the project team needs to accept responsibility for adding new chronological entries to the book. Secondly additions to the documentation can be in any form providing they are dated and signed and add to the progressive understanding of the system. Projects that have this approach are serious about making documentation the result of doing work and they reap the long-term benefits.