6 tips to create a better technical documentation?
Hendrix Roa
Building Scalable, Resilient & User-Focused Systems | AWS & IaC (CDK, CDK8s) | Expertise in Backend Systems (Python, Node.js) | Solving Complex Problems, Reducing Tech Debt & Driving High-Impact Architecture Patterns
Documentation is part of the process to give evidence about the things you did in your day-by-day work, along with reports, update meetings and catch up with clients, teammates, and bosses. Documentation is the log you leave if someone wants to understand all details of your work or extend it. That can be applied to a different type of work but at this time I will focus on IT technical documentation.
Is the documentation mandatory?
Yes, of course, that grant to the team a better understanding of the activities you did, avoid a bunch of meetings because if someone asks you some question related to a previous task you documented, you should only need to send the link to that with a brief explanation. Also, allow new onboarding people to catch up more quickly.
What time should be taken to write documentation?
Depending on how is your workflow, if you leave the task to write it later, the time you will invest will be longer than writing every day you complete an assignment.
How much I should document?
Make sure to not over documenting because will take your assignment longer and that task is subject to changes, only document the tasks you got approved.
As usual I will put the template I am using to document some processes at the end of the post.?
Here are the tips
Tip 1: Add diagrams
Diagrams can express workflow that could be a little bit complex to explain with words, but that does not mean you will avoid the text, but having first the overall picture of something makes it easier to read the text having in mind an image. No require to buy an expensive diagram tool, you can use software like draw.io at the time I am writing draw.io is free.?
Add external links, references
The text document is not required to be a bible of the project you are creating, explain which tools are you using, and add a reference to them. Explain the conventions and features you are adding, a good example is the terraform changelog where you can explain what happens in each version of your releases, or just can use a file features.txt or conventions.md to put all assumptions you have to start the project to get up and running. Readme.md is one key document you can guide technical people on how to install the project, the required tools, the links to more specifications, and so on.?
Document each type of project depending on the stack and programming language, here are a few examples:
Other options for restapi:?
领英推荐
Separate it: high/low level
High level
Explain everything briefly and without technicians, no need to be informal text but it is formal enough and self-explanatory (add high-level diagrams and images) because managers will check it. The high level should contain the following structure:
What: What is the thing the project pretends to solve, you should explain a brief background about the solution.
Why: Design decisions are taken for your team using business language.?
How: Procedure and workflow of the solution
Low level
Everything of high level plus:
Put it reachable
People struggle with that many times, and my advice put it in a place that is more reachable by the team, sometimes the companies have already licenses for products like
If your team/company does have not any license my recommendation is to add in the code itself, create a docs folder, and put all document files there. Important to know the markdown format to enrich the text and increase readability.
Take notes effectively?
At some point in the day, we take some notes from a meeting or a chat message with a teammate or manager addressing any situation. Those notes are your best friend to write any documentation because contain the exact amount of information that gives you a reminder about a task.?
Ask for feedback?
Last but not less, send the documentation to your teammates and your lead, they provide you with some advice to improve it.?
Thanks for reading!