These days there is a lot of talk about "documentation" around me. In the world of software development, documentation is often perceived as an annoyance, a necessary evil at best. This post is a follow-up on my previous post The right amount of documentation.

Documents are not equal, and many people fail to understand that some factors greatly influence how they should be written.

Consider the following types of documents, inspired from software development tasks:

• Notes taken for myself to be used in the following days
• Annotated sketches to be used to brainstorm with two of my colleagues in the following days
• Diagrams to be used to communicate with users in the following weeks
• Technical specifications for a subsystem to be presented to software designers and kept as reference
• The description of a software application to be used as reference in the organization by anyone who needs to understand what the application does
• A conformance document demonstrating that we comply with some ISO standard

Obviously, these documents will be subject to wildly different writing styles.

There are three factors that considerably affect how a document should be written:

1. Readers' knowledge about the topic: We have to understand to what extent the intended readers know the topic and the context. We can omit what readers already know. If you look at documents around you, you will probably notice most are either underdocumented or overdocumented. Assessing the appropriate level of detail is a critical part of efficiency, both for an organization and for an individual. We tend to err toward overdocumenting because it feels safer but actually it's just as damaging as underdocumenting, since maintaining heavy documents generates inefficiencies long after the document is produced.
2. Document lifecycle, or criticality: Most documents are not kept as references; they will be used for a limited period of time, for a specific purpose, then left to "die" (i.e. become obsolete). On the other hand, some documents will live as long as the object they document, and will have to remain up to date, possibly for several years. Long-lived documents are expected to influence the area they address much more than short-lived documents.
3. Adherence to existing standards: Why would someone reinvent how a project status or how meeting minutes look like? In many instances a quick search on internet (or on the company network) will yield decent Word templates for common documents. I have nothing against creativity, unless it's just for the sake of doing things differently.

I believe that standardizing the documentation process can significantly help. More on the tricky issue of standardization in further posts.

While working on Agile software development projects, we often hear that we should "avoid writing useless documentation", or "write the minimum amount of documentation".

However, teams usually fail to interpret this principle in the situation at hand. More often than not, the team only produces documentation that is strictly required to deliver the software to production. This is a case of developer myopia.

It's a matter of correctly interpreting the right amount of documentation beyond what seems obvious for developers. In other words, the documentation that should be created is not determined solely by the development team, but also by other stakeholders.

The following needs for documentation can be used as a checklist.

• Users need a user manual.
• Maintenance team needs a document that describes how the product works in order to fix bugs and make it evolve without depending on the team that developed the product.
• Teams developing or maintaining other systems need to know how to interface their systems with the product.
• IT infrastructure team needs to ensure reliable product installation and updates, to understand how to remove, start, restart, and stop the product's services, to implement application security, and to understand the systems and network requirements.
• Controllers and auditors need to assess applicable controls according to internal standards or standards such as ISO, without depending on the development team.

The more complex the organisation, the more diverse stakeholders are.

As you can imagine, it is usually after the development team is disbanded that the lack of appropriate documentation starts causing problems – big problems.

Agile doesn't remove the need for documentation, it helps optimize what documentation should be produced (as little as possible while satisfying the needs) and when (as late as possible).

Interestingly, it brings us to broaden the definition of value – a central Agile concept. If it has to be produced, then it does deliver value. Therefore, value is not just "working software", it's everything that stakeholders need.