How to document like your life depends on it
Learn to document the right way
All the way from startups to giant enterprises, product companies to agencies. We have not yet seen a single organization which documents properly. We’re not talking about them not having any form of documentation at all, they mostly do. We’re talking about “proper” documentation, as in the type of documentation which when you read blows your mind and allows you to get started in as quick as possible.
Why?
Everyone knows how important it is to have beautiful documentation. Yet for some reason no one puts enough love into it. Lack of documentation is one of the biggest contributors to new joiners having a bad onboarding experience as well as our best engineers having decreased levels of productivity. It also worsens cross team communication and hurts ownership.
It becomes even more important when working in an asynchronous environment. Not every colleague of yours will be in the same timezone as you are which makes it crucial for you to properly document you’re work so that your colleague can pick up from where you’ve left off. GitLab (one of the pioneers in the industry on the topic of full-remote) has made their company handbook available to the pubic which contains a lot of valuable information on the importance of documentation in the context of remote work.
Good documentation is especially important for companies which are in their expand phase. There will be more and more developers joining by the day. But also more code produced by the developers. Such an exponential growth can be done in a healthy manner by ensuring that the company has proper documentation.
But why is it that documentation is still either neglected, or not done
properly. Before we all jump on the bandwagon and start blaming our companies, we should first acknowledge that it is indeed extremely difficult to get it right if not impossible.
But it being difficult shouldn’t mean that we mustn’t try!
Whose job is it anyways?
Quite often, companies struggle with defining whose responsibility it is to
document the work. Should we look into hiring technical writers or should the developers document everything. Can Quality Assurance engineers chip in as well or should Product be owning it. In our experience, there is no one-size-fits-all solution, which means that the right answer varies depending on the specific context.
That being said, most companies will not have a dedicated role for
documentation. This usually means that the weight will be on the shoulders of the Engineers, the Engineering Manager, and the Product Owner.
Engineers should try to document as much as possible as they are the closest to the source. Technical READMEs, operational documents and architectural diagrams are the types of documents one should be thinking about. The Engineering Manager should support the engineers to help uncover any blind spots. There will almost always be something which is either missing or is outdated. An Engineering Manager would be the right candidate to help identify and fix them.
Last, but not least, there is also some work for the Product manager as any
product always needs to have a product style document which helps an external team member to understand what the intention of the product is and how to use it. This document should be accompanied by a Product Requirements Document (PRD) which well help with the context of why this product exists in the first place.
The gist is that you should do whatever works for you, as long as you do it!
What to document?
Another important aspect to consider is the type of documentation you’re trying to achieve. There is a difference between Technical documentation and Product documentation. Mixing and matching the two usually ends up being more confusing for the reader. Therefore it is important to understand who the reader is and in which mindset they’ll be reading the documentation. Are they developers who are trying to use the API you’ve provided to build their own product on or is it your colleagues who need to add new features to what you’ve been building. There is a difference.
A couple of topics which we believe are important to have well documented are:
Tips & Tricks
There are a couple of best-practices we’ve seen in the industry. Here are a
couple of ideas which might help you form your own documentation culture.
Documentation Driven Development
Similar to Test Driven Development, Documentation
Driven Development embraces the writing of documentation before the
implementation.
It is a relatively good idea however very difficult to enforce. Ideally
whenever the API changes, the documentation should be updated before everything else, however in practice, only before any development the documentation is well written however, with upcoming updates, the documentation gets neglected.
This approach works really well when you’re trying to design an API since it
will force you to think from the perspective of the user of the API. This will
allow the end result to make more sense, very similar to how one would do
Duck Typing.
Some of you might argue that this feels like we’re going back to the good old days. Where we are trying to design the system before building it. In practice, this method ends up being more iterative since developers first write the documentation of what they are about to build. Then start building whilst iterating over the initial docs. Once the first component is finalized move over to the next one.
Technical writers
Large companies usually have dedicated people who help with documentation. This is a wonderful approach as “Technical Writers” usually do a better job of documenting things compared to the engineers building it. A Technical Writer will also approach the tool/API they are documenting from the perspective of the user instead of that of the engineer which always results with clearer documentation.
The down side of this approach is it is costly. Not every company can afford to have technical writers. But if you can afford it, this is the best solution
amongst all others provided in this chapter.
The open source model
The idea of the Open Source Model is to rely on the community. Instead of
having a single person or team documenting the tool/API, we can rely on the producers as well as the consumers to help document. Usually, the developers will start with some basic documentation, which then is open to contribute to by others. Then, the consumers, as they start using the tool/API will uncover gaps in the documentation which they in turn with either highlight or even better, contribute to fix.
Auto generated documentation
Many Programming Languages and Frameworks do come with a way of documenting code inline. Java with JavaDoc, JavaScript/TypeScript with JSDoc, etc. Leveraging such language features will increase the quality of the documentation. Although one should not forget that the more lower level documentation gets (eg. documenting individual classes and functions), the more difficult it will be to maintain them.
There are also tools like Swagger and OpenAPI which can be used to help consumers have a nice high level understanding of how the API works without having to document individual classes/modules.
DocTests
One of the better ideas we’ve seen in the industry is the employed by the
Elixir programming language. Elixir comes with the `@doc` construct which allows the developer to document the module and/or function that they’re implementing. Elixir allows developers to use Markdown inside these `@doc` blocks which enables to developer to create elaborate inline documentation.
Furthermore, when a developer documents some examples inside the `@doc` block, the compiler picks those examples out and runs them as actual unit tests. This approach motivates the developer to document, as they get some immediate value out of it (unit tests), as well as allowing the developer to indirectly create documentation for the user of their code.
An example extracted from Elixir’s Atom module for such `@doc` block can be seen below. In this example, not only do we understand that the `to_string` function does (converting an atom to a string) but we also get an example.
Change
Whatever technique you choose to go with, it is crucial to understand the
concept of “Path with least resistance”. As we’ve already established,
documenting is not something which naturally comes to developers. On top of all the other things they need to consider, if we asked them to document things, the chances are already low that it will happen. But if we also ask them to use a tool which literally works against them to do the documentation, you can be sure that it will never happen. The change you want to introduce should ideally be an easier path to take, than the one engineers are currently taking.
This is where the tool you chose to write the documentation in really matters.
In the following chapters, you can find a couple of examples.
Notion
Notion provides a WYSIWYG style editing experience. You just launch the app and start typing away. You don’t need to jump between an “Edit” view and a separate “Show” view. It can integrate with various other tools which allows one to have all different forms of documentation grouped in a single place.
On top of its ease-of-use, it also has a nice community who are willing to help, as well as the company, which often listens to its users.
The only down side to it is the immaturity of its API (compared to that of confluence) which makes tracking of metrics slightly more difficult (but not impossible).
Git
The option of keeping documentation in code is the one with least friction for engineers. With this option, we stay using the tools which we already use day in day out (their IDE). We can leverage the power of Markdown (or any other markup language) and leverage mermaid.js (or any other Graph-As-Code tool).
Quite often, in the industry, we see many companies which create a single
repository (eg. docs.company.com) where all documents are gathered. This also allows the company to build a Single Page App using all the documents in the repository to create a web page which can be browsed easily. For those of you considering this approach, we would recommend using Docusaurus as it does a great job in providing the right balance between customizability and ease of use.
Confluence
One of the most common industry standard tool used in documentation is
Confluence by Atlassian. It is a tool with many features and integrations which is why at the first glance it appears to be a great option. The problem with it is the ease-of-use.
If at any point, you feel the urge to document something (which already happens quite rarely) then you need to:
Launch your browser
Go to Confluence
Find the page you need to edit
Click on edit and wait for a fair bit for the page to render the “Edit” view
Do the edit
Save
See the “Show” view and realize that you’ve done something wrong in the markup
Go back to step 4
As can be seen there are quite some steps involved. There are other tools which eliminate the need to have a separate “Edit” and “Show” views (WYSIWYG style) which greatly enhances the experience and reduces friction.
Metrics
When it comes to measuring the health of your documentation we have a couple of recommendations.
The first thing to consider are metrics around ease-of-use. After all, if you
have great documentation but it’s extremely difficult to find what you’re
looking for then it actually serves no purpose.
The standard metrics to think of around ease-of-use are:
Success Rate: How often are engineers able to find the information that they’re looking for
Time for Task: How long does it take for engineers to actually consume the information that they found
Error Rate: How often was the information they found wrong or outdated
User Satisfaction: How satisfied was the engineer with this experience
Supporting the ease-of-use metrics, we should also think about some quantitative metrics such as:
Lines of Documentation over Lines of Code: This will allow us to have a
normalized understanding of what rate of our code is documented (similar to code coverage)Rate of change of documentation: How often does documentation get updated
Using these metrics as a starting point, anyone can get a clearer overview of how well they are performing on the documentation front.
Conclusion
With all above mentioned examples, we hope to get you inspired to experiment with different techniques to help up your documentation game. As previously mentioned, none of the proposed suggestions will solve the root cause (which is that documenting is intrinsically a difficult thing) but it will at least help you remedy some symptoms.
What ever approach you go with, do not forget that people will always forgot to document. So it is extremely important to also focus on automation (eg. Continuous Integration pipelines checking for doc coverage, etc.) as well as processes (eg. Definition of Done, etc.) to ensure that all stays alive. Doing so will allow the next developer you hire to quickly become productive.