Why do we document?
Posted on September 19th, 2009 by Paul McArdle – 5 CommentsThis post was originally written to be part of a (lengthy) Book Review: The Tale of Two Systems (an overview of Lean & Agile software development).
However, I thought I would need to refer to this numerous times in future, so have placed it on our blog as a separate post…
The book talks about the production of 2 high-level documents that are produced in the early stages of the software development process - and which are used, thereafter, to guide the more detailed development path:
1) The “What and Why Document”
2) The “How, Who and When Document”.
The book also poses questions about the real reason why we need to document things (especially at such an early stage).
In my view, such documentation is useful for 2 primary purposes:
Purpose 1 = to Solidify Personal Thinking
Oftentimes (we all know that) we think we know something, but when put on the spot (to speak out loud or in writing) what we thought we knew well becomes a jumble.
The first purpose of writing something down is to help us assemble our own thoughts in a coherent fashion – i.e. something we can read, firstly, but also something that others can read as well.
For instance, one of my goals in establishing this blog is to encourage all our employees (and other shareholders, eventually) to advance their own thought processes in relation to issues of relevance to our business.
Purpose 2 = to Stimulate Discussion, and to Gain Consensus
Coupled with the first purpose, the documentation then provides a vehicle through which consensus can be reached about a way forwards.
In other words, the documents are very much iterative (i.e. living) documents.
Specifically – the document is a means to an end, not an end in itself.
MINOR Purpose 3 = as a Record
Hence, as a very much less important purpose, a document then serves as a record that can be referred back to later (after the fact).
Furthermore, the document should not serve as the ultimate litmus test of whether a project has succeeded or failed. That should be self-evident in the project itself (if you need to refer to a document to judge success, then that’s a telling sign that you have probably failed).
It’s nice to have, but certainly not a reason to write documents in the first place e.g. I’m certainly not writing this post to win a Pulitzer!
[...] In my view, the documents are primarily useful for two interrelated purposes: (I initially had this discussion here, but thought I would need to refer to it in other posts, so have put the discussion on another page) [...]
Hi Paul, this is a great blog you have created - gives a good personal insight into the company.
I think you’ve really hit on something with the Solidifying Personal Thinking point. Not only does it allow all people who are reading the document to have the same goals, same vision, and ultimately the same outcome but it offers the perfect time to analyze the outcome and the approach that will be taken to achieve it.
This “solidification” stage (whether a software project or anything else) is the cheapest time to find bugs, problems, or inefficiencies in what you are trying to do.
Skipping this phase opens yourself up to risks of missing inefficiencies in design, misaligned goals, and missing requirements. All of these can lead to:
- code that is more prone to software bugs
- more complicated code to maintain in the future
- missing functionality that pushes complications and delays later on
The way I see it is that an efficient documentation process may take some time and at times feel like wasted efforts but it should never be dismissed as such. The fact you have put such a focus on documentation says great things about Global-Roam!
I’ve subscribed to your RSS so I’ll keep up with your blog posts in the future
Thanks Nick,
I agree with you about the potential benefits of documentation, so long as:
1) The company does not become obsessed with documentation for its own sake (i.e. it’s a means to an end); and
2) The extent of “formal” documentation is commensurate with what is actually knowable at the time when the design is done - which is as I noted before, and might be aligned with the Agile & Lean mindset. In this sense, I would see more value, in the early stages of some projects, for more “informal” doodlings on paper to allow employees & clients to communicate about general ideas for what a product should be, without needing to follow a rigid structure.
Interested in your thoughts, based on your experience with the current employer?
cheers!
Paul
In a book I have just read “User Stories Applied” I saw the best explanation I have seen of why a focus on documentation all-too-often goes awry.
On p145 of my copy, under a heading of Verbal Communication is the following passage:
Whilst we could debate about the history less, I totally agree with the moral of the story. This is the point I was trying to make above (but poorly).
And, yes, I appreciate the irony of having read this in a document!
[...] I have previously posted in agreement with Mike Cohn’s view that, too frequently it seems, we have switched from a focus on shared understanding to a focus on shared documentation.