Too often documentation is looked down on as being a lesser task, as describing rather than creating value. This is unfortunate.

Once upon a time I joined an ongoing software project. Our software was supported on Mac OS and Ubuntu Linux. As part of my onboarding, I (of course) needed to install it. This installation was nontrivial, and in the process, I got stuck several times and needed to ask for clarification.

Figuring that others too might have this problem, I asked if it would be helpful to clarify the installation process, and we agreed that it would be.

In the course of this work I installed the software on one Mac and three Ubuntu Linux laptops. The output of this process was a clearly written Markdown document detailing the required steps for Ubuntu Linux installation. In addition, some related incidental issues were discovered and addressed.

For reasons not interesting enough to mention, it was a very short sprint, and this was my main contribution. At the end of the sprint, our team lead recognized us all for our contributions. There were specific descriptions of bugs that were fixed and features that were added, but when it came to my contribution, it was one word: “Documentation”.

Instead, it might have been described as “…produced a repeatable and clearly documented procedure to install our product on a fresh Ubuntu Linux install, to minimize time and effort required for developers and production to get up and running.”

…but it wasn’t. I felt undervalued. However, my team lead was super competent, attentive, and helpful, and I knew that any slight was unintentional; and upon further reflection, I realized that I too might have described my task this way.

Undervaluing documentation, and the people who produce it, is widespread in our industry. It is a prejudice many of us share.

The result is that:

  • some good writers will choose not to enter the field
  • developers will be reluctant to take this task on, even temporarily

The resulting reduction in the quality and quantity of documentation will then cause:

  • reduced productivity of new entrants and a greater cost of onboarding them
  • reduced productivity of existing members when they interact with parts of the software on which they haven’t worked
  • reduced adoption of the product (if adoption is optional)
  • missed opportunties for improvement that are revealed in the process of documenting
  • a degraded “bus factor”; increased dependence on individuals who might leave the project or be otherwise unavailable
  • increased costs of support to users and developers due to the lack of clarity

There is certainly a possibility of too much documentation, where it is made for its own sake, or is otherwise redundant or unnecessary. However, we should elevate useful documentation to the high level of respect it deserves.