How and Where to Document Software?

One of the first questions when starting a, or jumping into an existing, software project is where all the documentation is stored and how to access it. This means design documents, architectural diagrams, requirements, technical documents and other documentation that is needed. Sometimes it’s in office cabinets printed on A4s, other times it’s saved to /dev/null just to be safe. Fortunately, I have simple answer and that is: right next to your source code in the same repository. This is solely based on the fact that if the documents are scattered in different systems, they will not reflect the state of the software after some time. Secondly, if you want to automate part of the documentation generation from source code and link generated and hand-written documents together, it’s the easiest way to do it.

When you have realized that this is the way (sorry for the lame reference 😁), next it’s time to setup some tooling and formatting around the documentation. For writing and formatting I suggest using something that is easy to update together with the source code like Markdown or reStructuredText (rst). This allows easier diff of changes and eases checks in the code reviews (which you hopefully are doing). These formats are also easy to write…