Documentation is a task not many developers enjoy doing, not because we don’t find value in it but rather because we are not familiar with how to make it good or useful, in contrast to our understanding of how to make code good or useful. Our team was no exception to these struggles, so we explored certain ideas that would guide our approach to documentation. It is also important to note that our team mainly works on close-source projects.

I recognize that this article contains ideas that have only been tried on limited projects. While it worked on those projects, however, every project is different and has different requirements. This is not a company’s overall practice, but our team’s exploration of documentation for a particular project.

Proximity of Information from Implementation

Almost always consider the proximity of the information from the implementation.

Proximity to implementation describes how the complexity of information should increase as it gets closer to implementation. To explore this idea, take a look at the image below.

When looking at an object from a given distance, the only reliable information you can make of it is its general shape, which in this case is a car. As you move closer, some information becomes more visible, like the brand, model, and type of the vehicle. Inside the car, you might figure out its transmission type, interior, and other features. Getting even closer when you open the engine bay, with enough knowledge, you can probably figure out its engine platform, if it has a turbo, and many other details, again with enough knowledge.

In the given scenario, we take into consideration our closeness to the observed object. With software documentation, we can think of “proximity” as “the need to update” and “object being observed” as “implementation”.

README documents describe the overall idea of the project. In our car example, you are now outside of the car. From this point of view, you should be given a high-level idea of the project. The only time this document should be updated is when a car suddenly becomes a boat.

Question: How often do you check for markdown documents to see if it is also affected by minor code changes? Not that often, and for good reason. Its proximity to implementation is already too far to think of the specifics of the implementation. Documents such as these should never contain specifics that do not affect the high-level information.

Comments is closest to the implementation, because of its location that devs tend to have practices such describing the behavior of the function, explaining the parameters, and so on. The purpose of comments should be to give supplemental information on what you could not get from reading the implementation. In sports, game commentators do not repeat what the individual is doing but rather give insights on what the audience may have missed. Information like why there is a substitution or why a certain rotation is being done to counter a certain play.

Let’s examine the code below:

/**
 * According to Taxation Law #3117 individuals having dependents will have
 * lowered tax as incentive granted by the government. The computation is 
 * base on ( taxation table -> https://taxation-table.gov.fst ).
 * 
 * Last check on: February 27, 1620
 */
number applyTaxBaseOnDependents(number salary, number childrenCount) {
	number tax = switch(childrenCount) {
		1 -> salary * .05;
		2 -> salary * .02;
		3 -> 0;
		default -> * .1;
	}

	return salary - tax;
}

In this example, the comment added context as to why the calculation is done this way. It gives insight into the decision behind the implementation. The details of the calculation are also omitted since it is not difficult to read the function. Avoiding describing minor details of the function has a couple of benefits:

• It saves us the hassle of trying to keep the comment updated whenever there are small changes in the details of the function.
• No unnecessary redundancy of information.
• Avoid confusion. If the comment is wrong, does that make the code wrong or the comment wrong? The answer is both, and finding the correct answer would require effort when the cause was just that the developer forgot to update the comment.

Even though it is next to implementation, it is still not implementation. If we can, we should avoid writing something that would force us to update the comment for every change we make. Going back to our car example, comments are when you are sitting inside the car and can see the features it has. You can see it has an automatic transmission, but you are not seeing the gears that made it automatic.

As reference these are some of the industry leaders discussing this idea:

• Uncle Bob (Robert Cecil Martin) - Clean Code Talk
• The Elements of Programming Style - This is the link to the summary.
• Kevlin Henney’s talk Giving code a good name - in this talk he stated that the value of comment is derived from its scarcity.

Implementation is our codified solution to a problem. Although not written in natural language, I would still consider this documentation. This should not be hard to accept since it is still readable. Seeing code as documentation can remind us that not all functions need to have a comment. Maybe some inline comments don’t need to be there if we just structured our code better.

The idea of writing documentation with consideration of its proximity can be extended to “Progression of Information,”  but this idea can be an article of its own.

Know Your Audience

Documents have a variety of uses. Given its purpose, we should write these documents to whoever is deemed to be its audience. The audience of this documentation guiding idea should know the inner workings of the implementation and thus should have access to the code.

The team is working on a large code base, and there are a lot of responsibilities in order to maintain the project. Responsibilities such as code maintenance, data maintenance, and knowledge retention. Identifying the audiences of these documents should give us an idea of how to structure our documentation. For data maintenance, you might want it to look more procedural. Code maintenance would be more thorough in explaining the principles applied to the project.

Create Formatting Rules

Consistency plays a big part in making your document readable, and there are a couple guides you can use as references, but they might not exactly fit what your team and project need. Creating rules for your project document would really help the audience navigate and also guide the authors on how to structure the information they need to communicate.

Example:

# Project A
The search for the King of Letters

## 1. Introduction
This project aims to rank the letters based on how often a letter is used based on a set of a million unique words.

## 2. Instructions
### 2.1. Environment Setup
**Steps**
1. Admit that you like Perl.
2. Install Perl

### 2.2. Generating a million words
**Steps**
1. Go to Facebook.
2. Go to your wall and grab all your posts using the Perl script.

In the example above, we are making a README file for a utility project. The rules for the document can be:

1. Each chapter should be indicated by its chapter number; the rule applies to its subchapter.
2. A chapter should be formatted in H2, the sub-chapter in H3, and so on.
3. Steps should be numbered to indicate the order of execution.

There are a lot of formatting rules, and I am not suggesting that you ignore them. Rather, knowledge of those formatting rules should not stop you from building on top of them.

Summary

We undervalue documentation by not giving it much thought. Like code, if we don’t think about its structure, quality may suffer.