Creating documentation

Documentation can be written in many ways. There is no one correct approach, and it is often predetermined by the tools already in use, such as the repository service or the company wiki. Still, there are a few tips and tricks that will help you to write and maintain it, and we want to introduce you to these in this section.

Text documents

Let us first focus on the typical, manually written text documents. The classic approach is to set up a wiki, as these have the great advantage that they can be accessed and used even by less-technical people. This makes them a great choice for companies. Modern wikis, either self-hosted or software-as-a-service (SaaS), offer a lot of reassurance and useful features such as inline comments or versioning. They also can connect with many external tools, such as ticket systems.

Another option is to keep the documentation close to your code by adding it to the repository—for example, within a subfolder. This is...