Documenting

Documentation is not as fun as writing code, that's true. It is, however, when done adequately, one of the better investments you can do.

Documentation will first and foremost help you. You won’t update the entire system constantly. Some parts of code will not have any checks or updates for months. When v2 is requested you will have forgotten a lot of the shortcuts and why specific decisions have been made. You will have to rediscover them which will cost you time.

Source code level documentation is generally not recommended. High quality code is readable, contextual, and intuitive. If you write documentation inside your code, you will need to update it when changing functionality. Most developers fail to update their documentation, and you may read one thing in the comment, but the code will do something else.

There are a few types of comments in the source code that are useful in certain scenarios:

• TODOs that explain something that should be improved. Ideally, they will have a link to a ticket inside your system.

• Explanation comments as to why something is done in a specific way, for example unintuitive logic.

• Birds-eye overview of a module or set of modules.

The documentation outside of the codebase is generally of two types:

• End-user documentation that describes how to use the system, targeted at the audience who will use it.

• Technical documentation that describes how the system works, targeted at the audience who will maintain it.

One of the most significant advantages of maintaining high-quality documentation is that it helps with onboarding new team members. With thorough documentation, new developers can quickly get up to speed and start contributing to the project. This is especially important for projects with a lot of legacy code.

Examples of companies with great documentation include Amazon, which has detailed documentation for AWS, and Google, which has comprehensive developer documentation for their various platforms and tools. Another company with excellent technical documentation is Microsoft, which provides extensive resources for developers using their technologies.

Documentation is an essential aspect of software development that should not be overlooked. While it may not be as exciting as writing code, it is a crucial investment that will save you time and make it easier for you and others to understand and maintain the system.