On p145 of my copy, under a heading of Verbal Communication is the following passage:

Humans used to have such a marvellous oral tradition; myths and history were passed orally from one generation to the next. Until and Athenian ruler started writing down Homer’s “The Iliad” so that it would not be forgotten, stories like Homer’s were told, not read.

Our memories must have been a lot better back then and must have started to fade in the 1970s because by then we could no longer remember even short statements like “The system shall prompt the user for a login name and password”. So, we started writing them down.

And that’s where we started to go wrong. We shifted focus to a shared document, and away from a shared understanding.

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 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

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