Understanding Good, Bad, and Efficient documentation

In this section, we will reflect on the concept of good documentation. In practice, what counts as good and bad documentation is not black or white and will differ between organizations.

Good documentation is documentation that is read and brings value, such as helping to create working software, while bad documentation is documentation that does not help in such efforts. Let's look at some documentation aspects so that we can understand how to improve on the documentation process to make it better. To classify a piece of documentation as good or bad, you need to ask the following questions:

• What level of detail is required? At some point, the information might stop being useful and instead become cumbersome.
• Does longer always mean better? Does documentation always need to be lengthy in order to be better? Well, maybe in some cases, but not always. You could argue that you should only pack in as much documentation as you are willing to maintain.
• How hard is the process of documentation? How many steps are there to creating or updating the documentation? How difficult is each step? This heavily affects the efficiency of the documentation.
• Do we have the right tools? Having the right tools is critical for any task, and this is the case for writing documentation. By having the right tools, the documentation cost can go down, and the quality can go up.
• Do we have enough time and resources? As with everything else, documentation takes time and effort. You can't expect to have an optimum output and quality if, in a team of 10 developers, only one is tasked with writing the documents.
• How often is the documentation being used? When you are writing a piece of documentation, it is important to understand how often it will be used. The information that is contained in the documentation should be relevant, and also add some value to the team, so that it is being used frequently. It is very important to document correct, up-to-date information – the information the organization will need to read about at later stages. This, combined with easy access to the documentation, is key to successful documentation.

We can elaborate more on these questions by exploring them in the context of bad documentation and good documentation.

What is bad documentation?

Based on the previous questions, let's look at what indicates bad documentation:

• Detail: Too much detail is not always good. If you write about every bug, feature, loophole, and hiccup, it will become overwhelming for the users to find the primary functionality, as they will be lost in all this excessive information.
• Length: Generally, there is an incorrect notion with documentation that the longer it is, the better it will be. Following this, you may think that all the information in your document is important, but your readers may not appreciate it if the document, for instance, is over 500 pages long.
• Process: If the overall process of modifying and adding information to the documentation is too cumbersome and painful, and also requires a lot of steps and checks, then it stands to reason that the process will be expensive and, naturally, the contribution will be uninspired.
• Tools: Having too many tools to maintain your documentation can affect efficiency and distract the developer. For example, if we have a separate tool for diagram creation, another tool for text formatting, and yet another tool for controlling versions, then all this adds to the complexity involved in writing documentation.
• Allocated Time and Resources: With so much at stake and having learned about the importance of documentation, if you decide to rush through it so that you can add it right at the end, and not plan it in time, this will result in bad documentation. Imagine that you are part of a big team with only one person responsible for writing about everything in a limited period. If this happens, the overall quality will degrade.
• Relevance and Frequency: Most of the people within the IT industry, at some point in their career, have needed to spend a few days writing a document they know no one will read, just to be able to check some box in some process. This is a clear example of wasted time, resources, and energy, especially today, when so many are striving to use agile methods. This is also referred to as bad documentation in this book.

What is good documentation?

Good documentation simplifies the complexity of everything, and doing so in fewer words makes it even better. Let's look at what is considered good documentation, based on the previous questions:

• Detail: Keep the documentation to the point, short, and crisp. If you need to express detailed scenarios for loopholes or dirty tricks, create a separate manual for that. The readers of documentation want to find what they are looking for quickly; otherwise, they will not be interested in reading it further.
• Length: Does longer always mean better? Well, this is not always true. A 500+ page documentation may scare the reader, whereas a shorter variant of 150 pages may be appreciated more. If all the pages are important and required, then break them into smaller chunks that are relatable and easier to search, instead of one big, mammoth book. Note that if the short version excludes vital information, the longer version might be the better version. So, the answer to the question "Does longer always mean better?" is… only when it needs to be longer. Software documents should be as brief as possible.
• Process: A good process is a seamless one that does not require a lot of superfluous checks and automates the steps that can be automated. Examples of steps that should be automated include maintaining versions and auto-updating within the build. An easy process for writing and modifying documentation not only saves time but is more encouraging and allows contributors to have more fun while they write. After all, the most common problem with documentation is getting people to write it. A slick, fun process can greatly help with this!
• Tools: Markdown and Mermaid are a good combination for writing documentation. This provides the biggest advantage for technical writers such as developers, business analysts, testers, product owners, and so on. They are familiar with simple language instructions or code-like syntax for drawing diagrams.
• Allocated Time and Resource: To have efficient and good quality documentation, you should plan ahead, given that you have enough time and resources, so that it becomes a collaborative effort throughout the development process rather than an individual's pain.
• Relevance and Frequency: Writing good documentation is also much more rewarding than writing bad documentation. Compared to the preceding example, writing a document that people around you need and are willing to read attributes to good documentation. You might get positive feedback, questions about sections that are unclear, and requests for additional information. This document has an active audience and helps people with their work.

What is Efficient Documentation?

Writing documentation, locating it to read, and keeping it up to date can be quite challenging, especially in an era when the allotted time for most tasks seems to become smaller and smaller with ever-increasing demands for higher efficiencies.

At this point, we know how crucial and valuable the skill of documenting your project properly is. Often, as developers, we tend to work on different projects, and if a project already has good documentation, then we will be happier, more comfortable, and understand the project quicker. But at the same time, a lot of people don't get equally as excited when they have to write technical documentation. We need to understand why.

Another common problem that many of us face is that even though the project has been documented, most of it is not relevant or is outdated. So, why do some developers struggle with writing and maintaining documentation, and can we do something about this? 

By understanding the guidelines of efficient documentation, you can make this process easier. You practice efficient documentation when the documentation you create and consume is in line with the following questions:

• Is it distraction free? To be efficient means to do things in an organized manner, and to write documentation efficiently, you must be focused on the writing process. This means avoiding other distractions, such as juggling different tools and maintaining formatting for images, text, charts, and more. This is known as context switching.
• Is it searchable and reachable? No matter how good your content is, if the documentation is difficult to access, then it will be a pain point to the readers. Ideally, all the different documents in a system must be easily accessible, indexed, and searchable, so that the readers can find what they're looking for. Apart from a documentation system that allows for finding the right document, we should always choose a documentation system that provides easy access throughout the entire document. It should contain quick links, a search utility, and navigation across the document so that it is easier for the reader to follow it, process it, and use it to the best of their abilities. Good documentation is scannable and short. We should avoid walls of text; instead, we should add illustrations such as graphs and diagrams, since most people tend to think visually and prefer diagrams rather than long texts. The illustrations are also often used for reference.
• Is it easy to access when something needs to be created or updated? It must be easy for the documentation to be added, modified, or removed. The overall process should be smooth. This would allow more time for writing the actual content.
• Does it make it easy to see who made a change, what the change was, and when? It is important to see the timeline of the documentation and how it has evolved. As part of this process, we need to know what changes have been made, who made the changes, and when the change was made. This is helpful when you're clarifying that something new was discussed and added, and if validation from the author is needed; that is, to check the identity of who modified or added a particular change. In case of any confusion, you could reach out to the author and understand or validate why the change was needed.
• Does it handle multiple simultaneous versions of the documentation? For instance, one section might differ between different system releases and what is currently under development. A better approach from the developer's perspective is to have a documentation system that lets you commit parts of documentation to version control systems (such as Git and SVN), similar to how code is managed.

Guidelines for setting up Good Documentation

In software development, to make the overall process of documentation easier, faster, and efficient, use the following guidelines:

• Choose simple formatting rules and adhere to them: You should choose a formatting style for your documentation that covers the most necessary requirements and works well for the entire team. When you have a set of simple formatting and styling rules that everyone adheres to, it is much easier to combine their documentation. An example would be if you choose Markdown as the style for your documentation. Then, regardless of which editor everyone uses, as long as they write the necessary Markdown syntax, the output will be similar throughout.
• Make it visual: Add diagrams, pictures, and graphs as they make the documentation much more engaging and interesting. Using visual elements like this can help you explain a complex scenario, while making information easier to understand compared to just sentences. Adding visual elements wherever relevant is a good practice you should follow. The following image is an example to showcase the power of adding graphics to your text:

Figure 1.1 – An image illustrating the illustrative properties of an illustration

Here, you can see that the majority of the top GitHub projects contain full documentation and none of the projects have no documentation. This point is much clearer to the reader from the pie chart than if we were to just use text.

• Should support collaboration: You should choose a documentation system that supports collaborative documentation. Most of us work in a team or a group, and it is important for each of them to be able to contribute and access the documentation.
• Audience is key: To consider this, you need to understand who is going to read the document – is it the technical team, the business team, or somebody else? You need to make sure that the technical jargon and acronyms suit the target audience and their understanding of the topic; if the audience doesn't fully understand the jargon, it is not helping them, but instead making the document harder to understand. You should not assume everyone knows all the concepts you're talking about, and you don't want your readers to feel lost. Remember, we need to write to impress and serve our audience.
• Share examples: It is important to share examples (whenever possible) with the audience, for them to understand certain concepts. With the help of an example, they can easily relate to applying the underlying concept. For example, in technical guides for a programming language, it would be very helpful to use code snippets as examples for the readers to follow along and practice with.
• KISS principle: Much like the Keep It Simple, Stupid (KISS) design principle, you should keep the documentation simple and use short sentences.
• Be mindful of spelling and grammar: As simple as it may appear, spelling and grammar is also an important element so that you have effective and efficient documentation. Poor spelling and grammar might confuse and distract the reader, to the extent that they can't assimilate and understand the text properly. These issues may look painfully obvious, yet are often ignored in the documentation. Grammar and spell-checking plugins could be your friends here.
• Feedback matters: We are humans, and individuals think differently. No one is perfect, and we all make mistakes. Therefore, it is important to have a feedback mechanism in the documentation process, where positive and constructive feedback can be given to help us improve on the documentation.

Archiving Documentation

To overcome the problem of outdated and insignificant documentation, you should define proper rules for updating and archiving a document. Sometimes, an updated document affects the reader of the document in such a way that it conflicts with the old version. In such cases, it might be vital to make sure that the old version of the documentation is archived and only the new version remains in use. This could be a process description, a design specification, or similar.

When a newer version of a piece of software or a product is released, we need to update the documentation, but we also need to maintain older versions of the documentation as well, for those users who are using an older version of the software/product. Due to this, It is also important to maintain proper versioning of the documentation. Take Java versions, for example; for each new Java release, a new Java document version is introduced, but still, many people use older variants of Java. Due to this, support for those older variants of the Java documents must be present as well.

When it comes to regular minor releases, where only parts of the documentation are updated, version control for individual pages must be supported. If the rules are well-defined, this issue of irrelevant and old documentation can be mitigated to an extent.

Now, let's review what we've learned in this section before we move on to the next one. After learning about the importance of documentation, you learned about the key differences between bad documentation and good documentation that is worth writing and reading. You understood the concept of efficient documentation and the factors that drive how to achieve it. At this point, you are aware of the guidelines you must keep in mind before selecting a documentation system, as well as the best practices to follow for efficient documentation. Now that you've explored the good and bad aspects of documentation, you will learn about Mermaid.js and how it, along with Markdown, can help with efficient documentation.