How to make documentation less boring ?
Let’s be honest, writing documentation is usually not the funniest part of our developer job.
In this article I will try to go through various types of documentation that a developer can write. For each documentation I will try to say what its objective is, when and how we should write it.
By the end of this article I hope you can realize that documentation is essential and maybe, just maybe, not so boring after all 😉
🐘 The elephant in the room
Our time is not infinite and we could write documentation forever so it is important to establish a documentation strategy to see what’s relevant for you, your company or your project. Here are a few questions that can help you decide what you need to setup:
- 🧑🦱 What audience is targeted by your documentation ?
- ☣️ What part of your software or project is critical ? Business wise ? Technically ?
- 🤔 What part of your software or concept you use is hard to grasp ?
- 🙋 How many times did you go to Stackoverflow to get the same help for the same piece of code ?
- 🤯 Will you be able to understand this piece of code in a week ? A month ? A year ?
- 🆕 When a newcomer is joining the team, is he or she autonomous ? Can this newcomer run your app ? Easily add a test ? Contribute to your codebase ?
🤔 Documentation, who are you ?
Let me clear something right away: there is not such thing at “a documentation”. At least not in the sense of a single, holy documentation that would be perfect. Documentation is actually made of many pieces of various types and sizes. Technical documentation, tests, code comments, user guide, … these are all ways of documenting the code!
I will now go through various kinds of documentation and explain the goal they have, the audience they are targeting and when to use it and how it can be done efficiently. My list might no be exhaustive but it depicts when I use in real-world projects.
⚙️ Technical documentation
WHAT: Documents that help have a better understanding of the project or software. Technical documentation can include a Readme on how to setup the project, guides on how-to get started or how-to contribute to the project, architectural schemas, etc.
WHO: You, your colleague, yourself in one year, a new developer in your team
WHEN: Everytime something is not written or is not obvious for everyone (including a future team’s member)
HOW: You decide. Just remember that this documentation needs to be easily accessible (easy to find) and easy to maintain so try and keep it as close to the code as possible. Actually, the closer to the code, the better. I usually store my technical documentation as Markdown files in the Git repository of the project (e.g. in the root README and then in a docs/ folder at the same level), which can make it easy to access and maintain.
📄 Architecture Decision Records (ADR)
WHAT: Short documents on design decisions. ADRs help version your important decisions to keep a decision log and as such are a very interesting documentation for long-term projects to avoid losing all the decisions context as we go further with our project.
WHO: Every developer in the project, potentially a manager
WHEN: When you are discussing important design topics with your team. E.g.: setup of a project architecture, language rewrite of your project, CI/CD workflows decisions… or any other decision that will deeply affect the software being built.
HOW: By writing a small and versioned document for each decision. Don’t forget to add a new ADR when a new decision makes an old one deprecated, event two years later!
Note: ADRs were featured in ThoughWorks radar 2018
🧪Automated tests
WHAT: Unit tests, acceptance tests or any other type of tests. Automated tests help in reducing regression risks and offers a way of documenting what a piece of code or software does
WHO: Developers of the project
WHEN: Always 🧪
HOW: I’m sure you know, and if you don’t I strongly suggest you learn more about testing 🙂
💬 Code comments
WHAT: Code comments.
WHO: Your team developers for internal projects, other developers for publicly available projects
WHEN: When a piece of code or software is hard to grasp just by reading the code. Business algorithms are usually good candidates for code comments. ⚠️ Keep in mind that code comments should be used sparingly and that most of the times code can be refactored to avoid comment. “Don’t comment bad code: rewrite it”
HOW: Add a comment that actually adds value to the piece of code you are commenting, don’t just paraphrase what the code does.
🔀 Git commits
WHAT: Git commit messages can provide a very useful history of your project if they are done correctly.
WHO: Developers and anyone interacting with your project through ticket management
WHEN: Everytime you commit a feature or bugfix.
HOW: In order for your commits messages to actually carry meaning, try to make a commit for a single feature or fix. Avoid commits messages like “many fixes” or “miscellaneous”, they don’t add any value. Also, you can use conventional commits to carry even more meaning in your commits messages. Finally, don’t hesitate to link the task, ticket or issue that originated your development. Most ticket system (e.g. Jira, Github, GitLab, etc) offer an integration between itself and the CVS platform you use, which is very useful when you want to quickly find a commit associated with a ticket, sometimes months after your actual development.
🗞 ️Changelogs
WHAT: Short documents describing succinctly the changes you introduced since the previous version of your software.
WHO: Other teams in your company (for internal projects), other developers (e.g. for a public API) or even end-users for public projects like mobile applications and software.
WHEN: Everytime you release a new version of your software
HOW: Try do this automatically using conventional changelog (if you used conventional commits as mentionned above) to avoid doing it manually, it’s boring and usually doesn’t add much value.
💀 Postmortems & debug pointers
WHAT: Documentation that help recover from a failure and give context on why the failure might happen, and what action can be taken to avoid the failure in the future. Postmortems are a great way for your team to learn from its failures. After an incident (e.g. failed production deployment, big database issue, etc). Debug pointers are different, they help your fellow developers debug the application in case they need to investigate an issue. Both type of documentation aims at avoiding to reproduce past errors. Debug pointers might includes solutions or workarounds already tried, tries in attempting a fix that did not work, etc. It’s very useful to avoid the frustration of encountering the same bug three times and still not remembering how to fix it.
WHO: You and your developer team.
WHEN: Everytime an incident happen, everytime you solve an issue by applying a method that is external to the code. Note: ideally, reproducible solutions should be either fixed in the code or automated with a script to avoid doing manual steps to fix something.
HOW: Write a small document about the incident or add info to the technical documentation on how to debug a specific piece of code.
👥 User guide
WHAT: A comprehensive guide on how to use your application, library or software for end-users.
WHO: End-users. An end-user can be another developer, another company or any other people using your software.
WHEN: Before you release your software to your end-users.
HOW: It can be an automatically generated document if you are releasing a public API, or a manual documentation on how to use the specific features of your app.
🧳️ Final notes
Phew 😮💨
We’ve now seen quite a lot of documentation types, I hope you now have a better vision of what can be done on this topic.
I will leave you with a few key points to consider when thinking about documentation:
- 📄 Do write documentation
- ⏳ Try to write the documentation as you go: it’s way easier to write small chunks from time to time than writing an entire documentation set at the end of your project (it requires a lot of courage and you will have lost a lot of context by then)
- 🏋️ Practice. It might not be obvious at first when to write this type or this type of documentation, but as you go it will become more natural.
- 🧑💻 The closer to the code, the better. The reason is simple: it’s way easier to keep it updated, and can even be updated automatically by an IDE refactoring, which is great! Note: “close to the code” doesn’t mean that readers must clone your repo to read the docs, see point below.
- 🤓 Make it easy to write and easy to read. It should be easy to write simple documentation otherwise you just won’t do it: do what you’re used to, if you’re a developer, just use Markdown. It should also be easy to read, keep in mind people reading the doc won’t always an IDE or a tool for formatting Markdown: generate an HTML version of your doc if needed (CI/CD, Gitbook, etc). Which brings us to the next point…
- 👨👦👦 Know your audience. If your documentation reader is a developer you might be good with a Markdown readme or even unit tests but if your end-user is an app user you probably needs to generate a neat documentation!
- 🔢 Version your doc. Nothing to add, just do it 🙂
- 🔗 Help your user: cross-reference things. Reference another part of the doc, point a related piece of code, say what the user should head to after this chapter, etc. It might be clear to you how your documentation is structured but it is probably not the case for your reader.
- ✏️ Maintain your documentation: try spending maybe an hour a month to check if all your doc is up to date. Include this update process in your regular ticketing process to avoid the “we don’t have time” effect 😏
