A systematic approach for documentation

Documentation - sometimes dreaded by those who need to write it and sometimes very desired by those who need to read it.

Well-written documentation can make all the difference for a piece of software in terms of adoption, utilization and maintainability. In many cases, this is handled almost like an afterthought; it is something people do at the end of a project/product update - if there is time. I have been guilty of that a few times.

However, just as we try to be systematic about testing, design, refactoring code, we also should work systematically with the documentation. We can also apply principles similar to what we use for our code - docs-as-code.

Documentation lives in the same repositories as the code, whenever possible. It can be part of any automated CI/CD workflows to at least generate the documentation in whatever the target formats and locations may be.

Just as with coding, a bit of planning for documentation can go a long way in making the work a bit more efficient. Trying to answer a few questions is a starting point for figuring out what to do:

• Why - what are the reasons for providing documentation? Is it for end-user learning to use the software? Is it for a fellow developer to learn why the code was designed and architected in a certain way? Is it to provide reference information for an API that other developers will use? There can be many reasons as well as target groups, and you write documentation accordingly.
• What - what do you include and in what way should it be written? Tutorial, cookbook style, reference, deep dive into specific areas?
• When - Pick appropriate times to write the documentation. Sometimes it may help to write it part of the documentation first, like Amazon's future press releases.
• How - What tools and formats do you use? Markdown is kind of ubiquitous, but not necessarily the best option to use. Other text formats such as Asciidoc, ReStructuredText and RMarkdown may still be lightweight easy-to-read formats, and provide a richer experience in terms of what you can do with it.

For documentation within a project, I have found Architecture Decision Records to be quite valuable to keep a journal of architecture and design decisions made. It is a big topic in itself and not without challenges, but may be well worth it.

For some guidance and structure around what to write and in what way, I can recommend looking at The documentation system. Also, the site Write The Docs provide a lot of valuable material.

What tools to use will depend a bit on what formats to use for the master documentation, which in turn may depend on planned target formats and delivery. For the most part, I would say a lightweight markup format is likely what you would want to use. An example of a tool that embraces the docs-as-code approach is docToolChain.

As with other documentation, I plan that this post will be a living thing that I update with more information as time goes by. There is much more to write about this subject, but better make a simple starting point now and iterate on it than a big bang sometime in the future.