How to write good software technical documentation
This article aims to help developers to write better documentation. As a developer, I hate writing documentation. But I hate even more reading undocumented code. I describe here what I expect from a good documentation and why it is necessary.
First of all, you need to understand you are not writing documentation for you, nor for your current team. You are writing documentation for the future developers that were not there when you first wrote this code. Worst of it, they might think it is bad code for many reasons and won’t understand why you wrote this way.
Code documentation
I often hear that a good code does not need documentation. I totally agree with this statement. I am not here to explain how to write good code but good documentation. If you want to know how to write good code, you can start by reading this : https://medium.com/@isaaclyman/steps-to-better-code-e6c3cce0c7f9.
Naming should represent 99% of the documentation of your code. No need to add unnecessary comments to explain what you’re trying to do. It’s like as a French translator, you write some English comments in your translation for the next person that will update your work. We can easily guess that the next translator speaks both French and English, so he doesn’t need the text in both languages. It…
