Documentation guidelines in most teams seem to be repeating obvious truths: “Documentation is important!” or “Don’t forget about documentation!”
A good IT team establishes clear guidelines how, where and what to document. Most classifications of documentation stress the importance of the target audience. Non-technical end users are on one end of the scale, core developers at the other one. I like to classify documentation by two other factors instead: Cohesion and time.
Cohesion in this context is, how close the software is to its corresponding documentation. Would you rather have a popup telling you how to fill a form field, or look it up via Menu → Help → Registration Process → …? Same goes for internal developer documentation: Don’t put it in a Wiki, put it in your repository.
Time is, whether the documentation relates to past decisions, present behavior or future plans (Roadmap, Milestones, Tickets).
General rules
- Be as brief as possible but as extensive as necessary
- Strive for the highest possible cohesion
- Automate as many documentation steps as possible. High automation is equivalent to high cohesion. Manually drawn ORM diagrams are worse than generating them automatically from code
- Developers write the documentation. That way, documentation coverage and accuracy is higher
- Don’t mix the different types of documentation. In the following sections, I’ll explain them in more detail.
Documentation guidelines for the Past
Write good commit messages. As a team, reject pull requests that have unclear or unprofessional commit messages. Include why the change was made. Include a ticket identifier that will automatically be linked by your tools to your ticket system, therefore increasing cohesion. Use a standard for commit message format, e.g. Conventional Commits.
A commit log is not a changelog. While you can auto-generate a draft of your changelog, make sure to omit internal refactorings, comment typo fixes, etc. Make sure the changelog is human-readable. Target audience is downstream users and team members.
Keep decision logs in the same repository as your code and near the rest of the documentation.
Release Notes are NOT the same as the changelog. The popular online game “Battle of Wesnoth” is a good example of the distinction, as they provide a technical changelog alongside release notes for every release. Write release notes targeting non-technical end-users, even if you have a tech product.
Release notes should be written manually. You can take the changelog as basis, so you don’t forget an important change. Release notes double down as Tutorials. That way you don’t have to describe new functionality in two places. I strongly believe in written release notes over video content. That way, searching within release notes is easier, as well as tracking changes. Research on this topic.
Documentation guidelines for the Present
“How does the software currently work?” To answer this question, aim for highest cohesion and accuracy.
API documentation, SDK documentation and code comments should be as near to the relevant code as possible.
In languages supporting annotations (e.g. Java or PHP), prefer those over comments. Even better is replacing comments with code. Can better naming substitute the comment? Read “Clean Code” for some general comment guidelines.
For API documentation, use Swagger/OpenAPI.
Use context-sensitive help instead of an external help center. When thinking about where to place the code to show this help, refrain from creating a dedicated “Help Service” in a seperate repository. Keep the documentation near the corresponding code. This ensures that the documentation will be adapted, when something is changed. This is especially important in polyglot microservice environments, where developers otherwise have to write code and documentation in different languages.
Create setup instructions as README.md. In the linked document, I strongly disagree with the point “If you have ideas for releases in the future, it is a good idea to list them in the README.” It is NOT a good idea. Keep all your future plans in Tickets, Milestones, Epics.
A README is one-time technical „Getting Started“ documentation. It is of main benefit for technical users that want to use your product. Non-technical users will visit the homepage instead. The homepage is the place for feature comparison charts, video showcases and testimonials. The README is reserved for developers adding a dependency, API consumers, team members or those end users who are already convinced of your product and don’t know how to install it. Links to code of conduct and contribution guidelines are helpful. In general use Markdown links to other parts of your documentation, especially if there is a lot of it.
Documentation guidelines for the Future
A ticket system is the only way to plan the future of your software. Don’t put a comment “TODO: Refactoring” in a piece of code, write a ticket for it. Regarding ticket processes, there is already a lot of valuable information out there, so I will only share the most important points.
Let everyone (at least: within your company) see your tickets and create new ones through a structured process. Use a ticket template, that especially asks for the “Why” the change is needed. Create a sensible definition of ready. Make sure tickets adhere to the INVEST-principle.
Don’t use a Roadmap. Use GIST or a similar framework. For higher cohesion, ensure that all documented parts, e.g. company goals and sub-tasks, are kept in the same system (e.g. JIRA).
Buy into a stack that includes VCS and ticket system. If you use Bitbucket for your repositories, use JIRA. If you use Gitlab, use Gitlab issues. Fewer context switches and easy/automatic linking will be very valuable. I haven’t tried it yet, but IntelliJ Space looks particularly promising, as it is integrated with the IDE as well. Whether it’s Atlassian, Gitlab or anything else, it usually includes a Wiki. Be vary careful of using the Wiki for technical documentation, as it lowers cohesion.
If you need help with building your team’s documentation guidelines or processes, contact me. If you have any feedback, feel free to leave a comment.