Member-only story
Best Practices When Documenting Your Code for Software Engineers
It’s all about clear, asynchronous communication
As a software engineer, it is very important to acquire the skill of writing high-quality documentation. Due to the recent increase in remote work, it has become even more important to be better at asynchronous communication. Remote company GitLab does an excellent job of defining asynchronous communication:
“Asynchronous communication is the art of communicating and moving projects forward without the need for additional stakeholders to be available at the same time your communique is sent.”
High-quality documentation is an easier way to achieve effective asynchronous communication. In this article, I am going to talk about some interesting tips that I have found very useful in my personal experience.
Google Tech Writing Course
Google offers a free tech writing course for software engineers. It starts with the fundamentals of tech writing. There are two courses and the content is as shown below:
Being good at tech writing does not happen overnight. It takes practice. I personally prefer visiting this course each month to remind myself of the best practices.
Using the Divio Documentation Framework
Amongst all other documentation frameworks, I personally like Divio the best. The documentation systems suggested there are easy and universally applicable.
The framework suggests classifying documentation in the following types:
- Tutorials — Learning-oriented
- How-To Guides — Problem-solving-oriented
- Explanation — Understanding-oriented
- Reference — Information-oriented
