| Date | 2022-12-13 |
| Place | Techies Kraków |
| Link | https://www.meetup.com/krakowjs/events/290108992/ |
Schedule:
- Tomasz Borowicz – Tech News
- Mateusz Prusaczyk – Writing better documentation
- Mateusz Titz – Create better components and improve your (dev) life using Storybook
- Mateusz Lesiak – Animation performance in CSS and JS
Writing better documentation
I would like to present a slightly different topic. It is about writing, but not necessarily the code. I’m talking about documentation.
About me
A quick note about myself. My name is Mateusz, I’m a software engineer, here at codete – 4 and half years already. In my spare time, I also write a blog – softwarephilosopher.com. I write about this kind of stuff, like documentation, knowledge sharing, or tech interviews. The QR code navigates to the blog if you’re interested.
Does good documentation even exist?
Going back to the topic of documentation. Throughout my career, I have seen multiple projects. Some had decent documentation. Most of them had horrible one and some had none at all. I tried to understand what makes the difference. How to be like the companies that serve as an example of good documentation. What causes the documentation to be so bad in some companies?
Root cause of bad documentation
I identified two main themes. One is that we don’t have enough time to write. We finished the feature, we’re delayed already, and we move on to the next thing.
The second theme is that most people claim they simply don’t like to do it. .. (pause) At the beginning I also said I didn’t like to write CSS. What changed? I learned it. Therefore, my theory is that it’s not the problem with the documentation itself. It’s a lack of our skills.
And it makes sense. It’s not pleasant to do things under pressure that you don’t know how.
Kill two bids with one stone
I think that by improving our writing skills, we can kill two birds with one stone. We are going to be competent, so writing is no longer a struggle. It’s doing something we’re good at, and we improve the skill even further.
And because there’s always not enough time to write documentation, let’s use the time efficiently.
How to achieve that?
Sounds great. How to get there? I can identify four questions that can help us achieve that. Who, what, when, and how.
Who are you writing for?
We can start by understanding who our audience is. That could be analyzed in different dimensions.
Expertise level. Are we writing for engineers or non-technical people too? That can determine our word choice. I was very surprised when I came across the term CI / CD which in that context meant Corporate Identity / Corporate Design.
In companies that do not work in the technology field that could be even more visible. Do people who are not engineers know what is an API or a service or a component?
If we know we write for engineers, we still may need to understand the seniority level of the audience. Some obvious things for senior engineers could not be so clear for juniors. On the other hand, putting too much information into the document may make life harder for seniors reading it.
Domain knowledge is another thing to consider. After a few years in a company, we may be using their language fluently. But newcomers may have a hard time reading documents full of jargon and domain-specific terms. It makes sense to link the document back to other pages that for example explain the glossary.
Finally, people read the documentation for different purposes. We may distinguish two main groups: seekers and stumblers.
Seekers look for very specific information. They know what they want. So they would like to quickly find out if the document fits their needs. They appreciate consistency when scanning through multiple documents to find the right one.
Stumblers might not know what they want. They have a vague idea of what they need to implement., but need to gather more context. They appreciate the clarity.
What are readers looking for?
Because we know that people may be reading documents for different purposes we can make life easier for them. Too long; didn’t read section provides a nice overview and key takeaways from the document, so you know if this is what you need before you read it fully.
If we think about key takeaways and the possible outline in advance, the document itself may become more structured and focused, which is also a benefit. It is easier to list all the ideas and change the order and structure at this stage, than when you have a full document.
If you try to put yourself in the shoes of the reader you may also find out that less is actually better. You don’t have to cover everything in the documentation, just for the sake of completeness. Put information that makes sense and brings value.
Deciding on the type of document helps manage the expectations of the readers. Different types have different characteristics thus serving different purposes.
For instance, if we take Tutorials, we may expect that they are used by people who don’t know much about the system. We don’t have to be super complete here. Clarity is key here. On the flip side, the reference is complete. You go there because you have a very specific goal. You need this and this information and you expect it to be there. How does this endpoint work? What does it return? What kind of authentication does it expect?
Usually, with ideas explained in a form of a triangle, you can take two out of three. Of course, it’s not that extreme here, you don’t take only two, but you balance these. If you want the document to be more complete it will automatically lose clarity.
When should you write docs?
We know what to put into the docs. So we can ask ourselves when we should write them. That depends on the documentation itself but we can apply common sense here. For instance, if we’re talking about design docs we would rather write them before we start the implementation, right? And for public API docs or RELEASE notes, rather before rollout.
Usually, it makes sense to cover the concepts as we still have a fresh memory before we switch the context. I know it may cause tension, but it is at least worth trying to educate the team and product managers that documentation should be a part of the acceptance criteria and that we should not start the next story before we write about the current one. The benefit is of course it’s easier to get back to it in the future. Similarly, for incidents, we shouldn’t wait too much before writing a Postmortem, because we may forget some details.
But writing documentation is not a one-time act. It’s a continuous effort. Therefore we should make the editing easy or at least enable reporting issues. Newcomers in the team bring a fresh perspective and can quickly identify gaps. And sometimes at some random point in time, we may be talking to someone who explains something differently and we have enlightenment that it summarizes the problem so well.
Also, maybe an obvious one, but it makes sense to keep the information when the document was created and edited to know how fresh it is. Also, some tools, like for instance Guru, have a nice feature that periodically asks contributors to verify if the document is still valid, so we can see when it’s been last verified.
How should you write docs?
As software engineers, we put a lot of effort into ensuring the best quality of our code. We can have an easy win by applying certain practices to writing documentation. Review is one of them. We do a code review to catch obvious errors, we should do the same with docs. The simpler the code the easier it is to understand. It is the same with documents. Who wants to go through a big wall of text?
Speaking of which, we format the code to make it readable. Adding formatting to the text also makes it more enjoyable. Things like headers, paragraphs, lists, etc.
And finally single responsibility principle. It applies to what we talked about before, meaning the document types. They change at a different paces. If you mix them up, some parts may be outdated which results in readers losing confidence in the whole document.
Why should you practice writing?
We now have some guidelines on how to achieve better documentation, but as the last point I would also like to increase the personal motivation why it is even worth trying to be better at writing.
Firstly, for senior engineers, writing can work like a cache. Instead of answering the same question over and over again, we may redirect people to the specific docs saving some time for us.
In some companies like for example Amazon, writing is also part of the interview when hiring managers. And that makes sense, given that remote work is not uncommon, and most of the communication happens in writing. Also because of that, it is easier to reach more people by writing than by talking to everybody separately.
The QR code leads to the article that I wrote which gives even more ideas about why it makes sense to practice this skill.
Good documentation is achievable
I wish everyone working on projects with good knowledge sharing and decent documentation. It is possible but it’s a group and continuous effort, and we are all responsible for it.