Do you know that? You are working on an exciting new tech project, do your research, set everything up and it is working fine. But after some time, you want to change or recap it and you ask yourself “what the hell did I do there? I’d better written that down somewhere”. To be honest, most people, including myself, do not like writing technical documentation. It often seems to distract you from getting things done or seem boring. But believe me, writing technical documentation is more important than you may think now. Let me explain to you why and how to write good technical documentation…
Why do we write technical documentation?
We write technical documentation to document any product- or project-related information. That can be a project that is under development or already in use. Just think of some examples like API documentation, network diagrams, User manuals, and so on.
Most people think that technical documentation is just dry text that specialists with relevant education can read and understand. But that is not true. Nowadays we create technical documentation with visual elements like graphics, videos, diagrams, etc. Nobody likes to read long complicated texts, manuals, or instructions. Good technical documentation is easy to understand and provides detailed information simply and excitingly.
Especially when working in teams of any size having technical documentation is necessary. But also, if you are just working on your home lab, study for your IT certifications or do technical research, you should always document your process. No matter if you want to recap your project later or you want to share the information with other people. Trust me, you will not remember everything you did a few months ago.
Tips to write better technical documentation
Start with outline the topics and structure when writing technical documentation. Always think of the reader first. Who do you write for? Which goal the reader want’s to achieve? What information does the reader need to achieve this goal? What existing resources are available? It’s very important to focus on the reader and the goal, only write things the reader want’s to know. Short writing is good writing.
If you write text, use simple language. Because you don’t want to overcomplicate things. Make sure you don’t use long awkward sentences with complicated words. Remember, good technical documentation is written simply and excitingly.
Use diagrams, graphics, or videos to illustrate topics. Sometimes a simple graphic can describe a complex topic or architecture better than a written text. It also makes your technical documentation much more attractive and exciting to read. Pictures can say more than a thousand words.
Use Examples to show the purpose of any instructions or commands. If you use an example you can make things clear and avoid commands that are wrongly applied.
Best tools to write technical documentation
Confluence & Jira
If you write technical documentation just for yourself, there is nothing wrong with using any tool you like. Just use a simple markdown editor, notepad, code editor, or whatever works for you. Make sure you back up your files, upload them to a cloud provider or version control like Git. There are thousands of tools available and I do not want to cover them all in this tutorial.
Instead, I would like to show you a method I use to write technical documentation and that is quite common in enterprise companies. It may seem like an absolute overkill, but I think has a lot of advantages to familiarize yourself with these enterprise tools. Many companies use tools from the company Atlassian like Confluence and Jira, and these tools are well known in any kind of enterprise company. These tools offer amazing features and have many useful templates, plugins, and integrations to write world-class technical documentation.
You may wonder how you can use those enterprise company tools like a private person? Well, they are completely free available as an official cloud solution from Atlassian. You do not need to enter any credit card details and it is free up to 10 users. As small teams are not the main target group of Atlassian they do not have an affiliate program.