“Documentation.”
The mere mention of the word can cause visible shivers in many software developers.
While it is possible to talk about various types of documents and models in much more specific ways, and the relative value of each within specific methodologies, there is also considerable value in looking at this entire class of work products in general.
Why is it so hard?
This may seem like a painfully obvious truism, but most software developers are binary thinkers. The bit is either on or off. My program compiled without errors or it didn’t. My program crashed or it ran successfully. The users accepted it or they didn’t.
Unfortunately, none of the important questions about documentation have such easy, black-or-white answers.
How much is enough?
Most developers attempt to follow some sort of methodology that prescribes the creation of various types of documents. For each document type, certain content is recommended, perhaps with an accompanying template showing the suggested topics artfully arranged in some sort of hierarchical structure.
In all cases, the types of documents, the content of the documents, and the size of the documents are meant to be tailored appropriately to fit the needs of the project.
Unfortunately, when a binary thinker is presented with the question of how much of the prescribed documentation should be created, the two answers they are most drawn to — “none of it” or “all of it” — are also the two answers most likely to be disastrous for a project.
For a project of any size, writing nothing down at all is generally not a good option. People get confused, they forget things, and there is no permanent record of what they did or why they did it for later reference.
While it might seem unlikely that developers would produce too much documentation, there unfortunately sometimes arises a class of developers that can most accurately be described as documentation drones. If management emphasizes the importance of documentation, but then does not actually find the time to read any of it (as is often the case), their actions tend to produce people who are good at filling out templates and generating impressive-looking mounds of documents, even though, when someone attempts to read one of these things, the amount of useful, meaningful content turns out to be vanishingly small.
The right answer to the “how much” question, of course, is “just enough,” but most developers need some help coming up with the right answer here.
Attributes to consider
When talking about any potential document, there are three important attributes to consider.
Does the document need to exist at all? In other words, will its benefits outweigh associated costs and possible negative impacts?
If it needs to exist, how much of it needs to exist? In other words, how big does it need to be?
What form should the information take? Should it be a Microsoft Word® document, a spreadsheet, a database, or a graphical model created using some sophisticated, specialized tool?
The right questions to ask
In order to come up with the right answers to these questions, the following factors need to be considered.
Who will actually read this thing?
In other words, who is the intended audience? This could include customers, stakeholders, members of the development team, auditors of some kind, and/or future generations of developers who will be doing maintenance on the software.
What will the audience do with the information contained in the document?
Will developers use the information as a reference when they are coding? Will customers use the information to verify that you will be producing software that is useful to them? Will auditors use the information to ensure that the software changes had some legitimate authority? Will future developers use the information to help avoid changing the system in ways that are destructive to some original intent?
What is the likelihood that the document will actually be read and used for its stated purpose?
It is fairly standard practice, unfortunately, for people to accept a document, express some satisfaction at its creation, and even affix their name to it as an approving authority, even though they may not have taken the time even to read the executive summary thoughtfully provided in the first few pages.
What is the expected useful life of the document?
Is it simply being produced to help a developer clarify his or her thoughts? Is it being produced to assist other development team members? Will it be used by customers after the software is delivered to them? Will auditors need to refer to it? Are there some minimum retention requirements spelled out by law or corporate policy? Will developers continue to use it over the entire life of the software product?
What are the chances that the document will accurately be maintained over its entire expected useful life?
Developers are notorious for keeping system documentation sitting on their shelves, or stored in an electronic archive, even though it may never have been updated since the product’s original release years — or even decades — earlier. The decay rate of the documentation’s value in such a situation is blindingly fast.
Does the proposed content of this document duplicate information already available elsewhere?
Are people simply copying, pasting and rearranging words? If so, this is more likely to create confusion than to add value. Would the document simply state something that a developer could more easily deduce from the software source code itself? If so, developers’ time may be better spent adding a few judicious comments to the code rather than producing an entirely separate document.
What is the appropriate level of detail for the documentation?
One should be able to think about the useful information about a project or product as arranged in the form of a pyramid, with a relatively small amount of high-level information (design principles, overall system architecture, etc.) at the top, and a much greater volume of detailed information at the bottom. Keeping your documentation efforts focused towards the top of such a pyramid will maximize its value and minimize its cost.
Will the document explain “why” as well as “what”?
Often the most useful documentation explains why a certain decision was made, or why a developer is being asked to work in a certain way, as well as simply documenting what the developer is supposed to do. When the rationale is provided, developers are more likely to form appropriate mental models, and to act in ways consistent with the original design intent.
How will I assure the quality of the document?
One of the difficult characteristics of documentation, as opposed to software, is that it is difficult to determine its quality.
With software, you have both peer reviews and various forms of testing that can help to unearth quality problems. However, peer reviews of documentation are not nearly as effective as peer reviews of source code, and actual testing of documentation is often impractical.
If you cannot provide some reasonable assurance that the document will meet some minimum quality standards, then it is probably better not to produce it in the first place.
