Day 7 – Documenting

Some of us, developers, do have a weird relationship with documentation. All of us love it when we need it and very few of us are willing to write one.

Probably the worst opinion on documentation which I have encountered so far was that “documentation is useless because no one updates it”. This stance is toxic not only towards other people but also towards oneself. In my opinion developers need to take responsibility for documenting what we code.

While working on SlothCMS I created several types of documentation which worked only during certain stages, some are still useful and some need to be implemented. Starting with those that have been found useless and are now thrown away, issues on Github. Having a bot which will create an issue whenever a developer writes todo  in comments sounded like a good idea to me at some point but it didn’t last through the battle. The main reason for its failure was its location because it’s not in my editor I don’t see it so the issues became stale and after some time the only thing to do was to close them.

What is always useful are docs to old code which solves similar issues. This is not the first round of implementation of SlothCMS, it’s more like third one and some problems I already have encountered. So unless it’s something language or framework specific it’s worth looking at algorithms which were used before. One has to be careful when using old code because past you or other developer might have abandoned it because they were deep down the rabbit hole, found a dead end and couldn’t finish it.

Another thing that’s useful is paper documentation. Being a visual person I rely on drawings, especially when it comes to coding because drawing a diagram for me is easier than describing an algorithm in words. So a lot of my SlothCMS docs are written down on paper and therefore off-line.

Digital documentation is a thing that I will have to work on. Mostly because as somewhat inattentive person it’s easy to misplace a paper or two with diagrams. The main issue is how to make it more accessible and inviting to edit compared to Github issues.

Other digital documentation are comments in code which I admit I love but haven’t build a habit to write them all the time yet (I need to work on that).

Anyway, one thing that I consider a success is that I don’t feel guilty for writing documentation instead of code. I used to feel guilty because past me didn’t consider writing docs as productive as writing code. These days writing docs can save a lot of time of writing code, so I consider it more productive.