Tips for Writing Better Documentation
We all know documentation is a very important but often neglected part of tech, and we can all recognize how game changing finding good documentation can be. Sadly, at least in my experience, if you’re working on a project, especially if it’s volatile and there are many changes, it can be hard to constantly update the docs to describe the latest version of the project. Then usually towards the end of the project, it’s often an “onto the next” mentality and the documentation of the project you just worked on is often left incomplete or out of date.
From having joined multiple organizations with extremely out of date documentation, or simply none at all, yes, quite literally no technical documentation as it was all in the heads of a handful of people, it can not only be frustrating for new joiners to the team, but also creates a lot of major functional problems in how the team operates.
How can we expect someone to onboard and learn about the project’s they’re meant to be working on if the only reference for the internal toolings/practices are only verbal? How can we expect the team members with all this knowledge in their heads to take hours out of their day to write documentation when surely they have more important things to do?
These are just some of the questions I hope to help answer and provide tips on generally writing documentation that should be understandable to anyone within the organization, not just people on your team or engineering.
Don’t overcomplicate things unnecessarily.
I always like to think that good documentation should be simple and straight forward, it should explain the context behind the documentation (why is the tool, task, or documentation page being created) in a few sentences, then how to do whatever you are trying to achieve. If it’s a guide on how to set up an EKS cluster, for example, you don’t need to include a bunch of documentation about what K8 is and the history of EKS. These can be created as a separate document under the same section. Instead, the document should outline the scenario in which this document is relevant, and then a clear step by step instruction on how to achieve the EKS set up.
I often like to think, if I can show this document to my tech illiterate family members, be that grandparent or parent, and they can get the gist or a decent understand of the doc, then it’s comprehensive. Of course not all documentation can be simple, but trying to simplify as much as possible within the context of the document topic can help.
Don’t be afraid to link to external sources.
None of us know everything, and we don’t necessarily need to spend time re-writing something generally used in tech within our documentation when there are many, very good, external sources which already explain what we are trying to achieve.
For example, if I’m trying to write a document explaining the architecture of an EKS set up and I want to describe how to resolve an issue during set up that may occur with the kubelet, you can assume 90% of the people reading the doc know what the kubelet is, however, finding a good link that you feel describes very simply what a kubelet is and then referencing that in your doc can allow people to go deeper and gain a better understanding. It can also be helpful when you’re writing the docs as there could be more context around the subject of the document itself.
Define what pre-requisite knowledge is required.
It is very probable that the majority of the people reading your documentation are engineers, however, it’s also possible that non-engineers or people without the same context as you on the project will be reading your document. Adding a section at the start to define what knowledge is required to fully understand the document, or even, complete the required tasks in the document can be critical in helping it be understood by a wider audience.
For the busy engineers, carve out time in your schedule to catch up on documentation.
It’s easier said than done and I’m fully aware of this, we all say “here’s an hour where I will write docs” but then you get a ping or an email or something higher priority comes up and next thing you know there’s a draft or a half written document that get’s forgotten about. I’ve definitely been guilty of this.
Ultimately I think there’s a few things that lead to it, one of them is how highly does the organization value documentation? I’ve been in organizations where the issue of literally no documentation was raised to a manager and the response was “it’s not important, we will get to it later”, of course, later never arrived. Sometimes it’s the mental effort, documentation can be incredibly draining to write, especially at the end of a long project where the initial view of the project has evolved over time and there’s now a lot to document.
Having a regular hour or two during your week, for me a Friday afternoon usually works, in which you mark yourself as do not disturb on slack and just focus on updating any out of date documentation or creating new documentation can help the overall team and organization run a bit smoother.
An architecture diagram says a thousand words.
As the old saying goes “a picture says a thousand words”. Sometimes, if you’re describing the workings of a system and want to effectively show how everything works together, words can often be too confusing or convoluted. Diagrams can often serve to simplify this by creating a visual aid to piece all the technical text together. Many of us are visual learners and having a visual aid means that not only will your reader perhaps understand your overall document better, but it may also help them remember it better.
There are so many more tips, but to avoid writing a massive post I’ll just highlight some of the more common ones I use as well:
- If you’re writing a step by step guide, ask someone who is unfamiliar with the tasks in the guide to test it, if they get confused, lost or have many questions, just means the guide needs to be clearer.
- Keep it short, no one likes to read text that rambles on forever, try to keep the document short and to the point.
- Don’t be afraid to write documentation, you can always go back and edit it. Often if you find there is something that should be documented but isn’t, this is a perfect time for you to not only “add value” to the team, but also practice writing documentation. As with everything, the more you practice the better you become.
- It can sometimes help to define the intended audience at the start of the document. If you’re a DevOps Engineer, you will need separate documentation for developers on how to, for example, interact with the CI/CD tooling vs what your team will need to interact with the tooling.
Thanks for reading :)
