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:, 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.


Avatar for Ana VG

Written by Ana VG

Junior Frontend Developer | Lifelong Learner


Fetching comments

Hey! 👋

Got something to say?

or to leave a comment.