How to get along with Documentation
I don’t know what the recipe for success is, but knowing how to keep record of a software project should definitely be one of the ingredients …
/* Issue to be solved */
After finding myself googling on the same questions/topics over and over again, I realize a new approach was needed in order to save time and skip the hundreds of millions of lost hours reading Stackoverflow.
So, time to get along with documentation.
/* Excuses for not doing it */
In order to stick to it, and find motivation to keep a consistent project documentation, I first need to find the reason why we might refuse to do it. These are 4 potential reasons why we do not keep record of our software process.
Might be boring: is not the funniest thing in the world for some developers. It’s not priority: it’s always going to be more important to fix a bug, work on a new feature, etc… So it might no be a to-do task or priority. It goes out of date quickly: due to the evolutionary nature of a software project, if the documentation is not maintained, it can become out of date very quickly. Not 100% sure it will be used/read again. Although the previous points might be totally valid and true excuses, why is documentation so crucial?
/* Consequences of not documenting a process */
Well, it turns out that not documenting a project has certain risks that can be troublesome, annoying, and cost time or money. Based on my experience, I found that there could be 3 main risks related to time and information.
Risk 1: Having to do it when you don’t have time or remember anything. Risk 2: Valuable information can be lost by forgetting something important or by simply rotating DEVs. Risk 3: Losing too much time looking for a solution to a known problem.
OK, so far we have a lot of excuses for not documenting and various risks that could exist for not doing so. So what should you do as a DEV to avoid these problems?
/* Solution */
Set practical priorities: Minimal documentation is more doable than promising the best documentation you’ll ever write once you finish your project. Break it into small bits: By dividing the documentation process into the following 3 parts it’ll be easy to be tackled. Integrate it in the main milestones: Make it part of the process. Good practice
Keep it updated: The documentation is a living tool, it must not be allowed to become outdated. Document what is important in files (eg: README.md, CONTRIBUTION.md) so they can migrate together with the project and are not separated in a Wiki or similar. Document any important thing: do not take it for granted that something is obvious or not important enough to be documented, meaning you should include: commands to start or run the project, environment variables needed to set up an initial configuration or similar, or frequently asked questions about common problems. Be clear & practical: It must be understood above all as well as practical, avoiding long, unuseful paragraphs.
a.
