Documentation Engineering
In this article, we take a look at technical documentation writing from a software engineer's perspective. We briefly examine the correlation between software and documentation creation, mentioning the practical implications of that. It is done by drawing on the example elements of requirements analysis, design strategies, and programming principles.
❗Note that exhaustive research is beyond the scope of this article. Regard it as an introduction to the application of engineering methods to documentation writing.
Kinship
Even though the creation of software ⚙️ and documentation writing 📑 aren't identical, they have similarities. This is natural since in both cases we are building a system, and any correctly addressed system is constructed with general engineering methods in mind.
Furthermore, these code-written and text-written systems align in what they mean to achieve. Computer programs enable the automation of reiterative workflows and processes. Likewise, documentation — being aimed at enhancing information communication efficiency — enables, in a way, the automation of 🗣️ information distribution.
Due to the kinship, the documentation writing process can be optimized by applying software design strategies. On the other hand, the resulting texts can be refined by conforming to some of the computer programming principles. We illustrate these points below, reflecting on a few of the particular approaches.
But before that, let's consider what should be documented first.
Priorities
Observe that the most often repeated and costly (that is, requiring many resources) operations are selected for automation first. It is reasonable to do the same when choosing a subject to treat in a document.
The first type of subject is easy to find in repeatedly asked questions and trending communications. These are most effectively addressed in getting started guides, FAQs, Wikis to some extent, and similar.
Subjects of the second type — the ones that take a lot of time to explain — are best covered by foundational (conceptual) manuals, specialized instructions, tutorials, flowcharts, detailed API documentation, etc.
Strategies
Now, according to the promise given above, we review two of the design strategies. Flexibly combining and utilizing different strategies helps with the following major aspects:
- Better organize the process of implementation.
- Ensure a well-structured end product.
Top-Down Approach
Frankly, this is my favorite strategy for implementing any system, especially in the early stages. With it, we start with conception, planning, and developing the most general aspects. Gradually, we move on to working on more and more particular elements. In the end, the most specific details are finalized and polished.
This is all perfectly pertinent to the documentation-writing process. Begin by outlining broad ideas, then amend and specify them. Structure a document such that it facilitates the expression of major notions. Advance to writing down general considerations, then more specific thoughts. And so on, up to the point of the final text verification.
Anyhow, sometimes it gets difficult to progress with this approach. When this happens, try resorting to the opposite strategy, described below. 👇
Bottom-Up Approach
With this approach, we primarily concentrate on specific, smaller segments of a system (documentation). Then, by interlinking sufficiently developed elements, we construct subsystems. Gradually composing subsystems of an increasingly higher hierarchy, we eventually form a complete system.
Oftentimes, the incorporation of both strategies yields the best results. Switching focus between them in accord with actual circumstances aids not only in moving forward with an implementation but also in better comprehension of the system as a whole.
Principles
Lastly, we explore two of the programming principles in the context of documentation writing.
KISS
The KISS principle is an acronym for the phrase "Keep it simple stupid" (variations of this phrase exist). It suggests pursuing simplicity as a key property when designing and building a system, because excessively complicated systems are difficult to use and maintain.
Correspondingly, a documentation that is bloated, contains unnecessary details, or has an overly complex structure is difficult to comprehend. Writing in fittingly simple language, using clear terms, and avoiding convoluted sentences are good practices for adhering to the KISS principle.
Everything should be made as simple as possible, but not
simpler.
— Attributed to Albert Einstein
DRY
The name of the DRY principle is shortened from "Don't repeat yourself". In programming, it rightly advocates for the elimination of code and data repetitions (through abstraction and normalization). This minimizes the possibility of negative after-effects when bringing a change into a system. After all, it is a daunting task to track all the places that have to be updated simultaneously. Disregarding the principle obstructs maintenance and leads to the emergence of bugs.
The same principle applies to documentation. Introducing a feature or concept in multiple sections of a document demands additional editorial effort to keep it up-to-date and consistently represented throughout the text.
However, it's important to note that varying descriptions of the same feature or concept in different types of documentation (e.g., user manual, developer manual, tutorial, wiki) is a fine approach when put into practice thoughtfully. In each case, a topic should be reviewed from a certain angle and written for distinct audiences. A common good practice is to interlink related descriptions, potentially offering readers a complete picture of a topic.
Phew, and that's it for now. Additional analogous considerations are left for the reader's exploration. The following ideas should assist with that:
- Use of meaningful, distinct naming.
- Adherence to conventions.
- Laying out basic definitions to further build upon them.
❗ In conclusion, with all that has been discussed above, remember that strategies and principles are only means to achieve a goal, so pick them up as tools matching the objectives.
