@radekmieBy Radosław Miernik · Published on · Comment on Reddit
Writing a good piece of documentation is a heroic task. You have to deal with tens of small nuances on each sentence – or even word – just to make sure that everyone will understand it. You may think that you won’t be that everyone anytime soon, but if you’ve seen things, you realize that sooner or later, you will be. Most probably sooner than you realize.
If you were lucky enough to work in a well-documented project – or should I say environment (I’ll get to that) – you should know that keeping it this way takes time. A lot of time. The details, like formatting, correct wording, style of the charts, or even doodles1, are probably the most time-consuming.
Hundreds of (mis)formatted Confluence pages, some ancient severely outdated Google Docs, stale-since-ever Jira tickets, way-too-brief meeting notes on Slite, and a bunch of random Notion pages. If you are lucky, you have people (most probably a single person) who actually know things. And they are here since… Ever? They won’t leave.
They won’t, right? Right!?
Everybody dies…1 Our colleagues do, too. Maybe not as often as our grim thoughts make us think, but they do. Or, alternatively, they may get hit by a bus and be off for some time. They may not be available for an extended period of time for a million reasons, actually.
Here’s my take on five stages of grief in IT:
Sounds oddly familiar, right? I heard the first part way too many times. And it’s not an IT-only or even commercial-only thing. People come and go – that’s how it works. Denying and ignoring that is definitely not going to help.
Have you realized that the documentation is necessary yet? Congratulations! That’s like, half of the job. Now, let’s get to it. We have to choose a tool, then designate the first person to start, select the most important topics to cover at the beginning… Aaah!
Most of the projects I’ve seen have had at least a gist of documentation. Almost always, the tool was already selected and set up, everyone has been onboarded, and yet, nothing is happening2.
After an accident (or three), you’ve created a guide on how to mitigate and deal with them in the future3. But as nothing “bad” happened for the next year (everyone was extremely cautious, duh), these became obsolete and unusable.
Occasionally, one of you starts taking notes when a new feature emerges. It’s sweet for the first version or two, but then the requirements change, and they no longer know how to keep track of that.
Finally, there’s that single README.md in the root of the repo. Not because the manager wanted it there, but because it was actually needed. Onboarding new people was too “focus consuming”, and creating a step-by-step guide of shell commands was a great way of making sure that nobody would mess it up4.
“Let’s make a plan to create our documentation in such a way that it’ll be easy for everyone.” Sounds good, doesn’t work. Mainly because it means completely different things for different people. That’s why you should have a glossary.
Whether it’s a name of a role, view, operation, flow, feature, or even that one big client – it’s worth making it explicit. New people joining the project should feel at home, not be greeted by many inside jokes. Try using these names in the code as well – code reviews will get easier and more precise5.
What is more, such a glossary comes in handy when you interact with less technical people. For example, the clients or marketing team don’t (want to) know what’s in the code. But if they’ll ever see an error (they will), maybe they’ll figure out who is the best person to reach to on their own. At the end of the day, it may be a good idea to talk to them every now and then.
Even the word project that I overuse in this text is quite vague. Here it’s actually a good thing, as I’m not exclusively talking about software or even IT. However, I really enjoy thinking in environments instead. It’s less specific but manages to capture the human factor; “we are the project” is a no for me.
Pick a tool. Anything, really. Just stick to it, at least for a little while. Don’t worry; if it’s going to be an issue, you’ll make a switch. I’ve seen such migrations, and they, of course, take time. But it’s definitely less than the time you’ll waste on evaluating seven different tools. If the team is familiar with something, this may be a good first choice.
Then set some ground rules. Like, how to link things, what font style to use, where to put images, etc. Decide on the basic structure of it. If possible, create templates. It all may will change over time – that’s natural. This is just a start.
Now… Write docs. Not too many. Mostly user flows6. Start small, with a glossary of a few words; add them as you go. Add some screenshots. Link to tasks, Slack discussions, maybe even code. If it’s getting too noisy, split it into sections or even multiple docs. Just keep them close, so they don’t get lost.
Knowing when to update the docs is as important as the contents. You may do so during planning (then if the solution is delayed, the docs are “outdated the other way”), execution (this slows the entire process down), or once everything is done (there are more important things now). They all have their ups and downs; try them all and pick the one that suits you most.
This is definitely not a tutorial on writing good documentation; it’s not even a tutorial. It’s more of a rant on my past self, sprinkled with a few good hints. All that learned the hard way. There are some slides as well.
Documentation is an art in itself. Not only the process of creation – the fun of using it, the thrill of not finding something, the smirk you make while scrolling over that funny doodly for the tenth time that day. All of it.
Now go. Take your meds. Write your docs.
When was the last time you’ve actually drawn something? And yes, I do mean using your pen and paper or whiteboard – not diagrams.net (formerly draw.io). There’s a big pile of A4 sheets on my desk at the office, but since the remote work started, I completely stopped. On the other hand, I regularly work with both blackboards and whiteboards. When combined with some scanning software on the smartphone (I recommend Dropbox), they make the best meeting notes ever made.
…surprise, surprise. Thanks, Billie.
During my proffessional career, I’ve met literally a single person who actually enjoyed maintaining the docs. And it wasn’t only that – the results were more than great! It’s hard to tell whether it was a skill, a gift, or a curse. Nobody else was doing that. In the end, once the person left, no one continued.
Writing so-called post mortems is a fantastic practice. Going through what actually happened, what actions were taken, and how much time each step took is crucial to improving it in the future. Also, they make the best content for your dev blog: here’s a bunch from Cloudflare.
Sometimes it’s best to let people fail. However, it’s not a good idea when it may cause casualties. (Yes, an evening of yours is a casualty.) I wrote more on it in On Ad Hoc Mentoring.
Writing code also becomes more straightforward, as it’s an integrationId, not just any id. Getting rid of thinking while writing gives people a chance to stay focused longer.
Check out Write tests. Not too many. Mostly integration. by Kent C. Dodds.