Technical Documentation Terribilis

Technical Documentation Terribilis

Sometimes when I read technical documentation for software libraries I feel like I am reading the draft of a novel jotted down by a drunk writer. It is not finished, it is not clear and worst of all it just doesn’t make sense. And yet I have to read it to use the given library. So the remedy to that in general is to skip the library at hand and search for a better documented library, or if really you are stuck with this library dig through the code and find out for yourself what parameters you can use. It is terrible. I think it’s a massive waste of time. A normal person would ask, so why don’t they make clearer documentation? Well, very good question.

You see, the developers culture is very very particular. In fact it might be the only technical field where the less clear it is, the  better because you feel more empowered as a developer, because even if the documentation didn’t make sense at all, in any logical sense possible, you made it and traced back the logic. Like you just climbed some unknown very high mountain on your own. It is, it is like that. And you see it in every day development practice. Instead of making diagrams or exposing clear APIs, developers always hope people get what they mean by reading the code. They write code fine because writing clean code is already documented in books. But writing documentation is not made a good practice enough. And no, you can’t count on code self-documentation when you deal with big libs. In fact, someone who asks for documentation is always viewed as the one who can’t climb the mountain barefoot. I took note of the problem actually one day when I asked a guy “why didn’t you update the documentation if you struggled with the same bug as me?” He said in a cowardly joking tone “I dunno, because I was too ashamed I couldn’t make it work”.  And another time, in an ironic (I hope) humor “nano?! No, I would never use that. I prefer Vi, so much it is unclear, the more confused, the better really.” That’s when I understood the problem was cultural. The problem with the previous guy is that he blocks the documentation chain for everybody coming after him and he makes people waste their time on bugs that he already identified but didn’t report.

Well, I always reason in terms of arguments, and really my main argument is TIME. If something makes your organization waste time, just DROP  IT.  Letting developers  struggle with undocumented processes and code is a massive waste of time, because the time they use to figure out information that is well known by someone else and could have been easily documented is time they could have used to bring value to your organization by thinking, producing and creating, it is really wasted time. It’s like letting people find a place on their own when they could have found it much faster by using a map or better yet a GPS. So consider it like this, writing good documentation doesn’t make you less of a good developer, all the contrary. Just imagine a plane’s documentation. Writing documentation is like pioneering work, it’s mapping an unknown territory, yes MAPPING.

With good code comes good documentation.

— me.

Really!

I have always perceived that weird cultural (ridiculous) trend in the dev culture but I couldn’t really give a tangible example. And then, when I read the surely poetic git rev-parsed doc, I felt like all the dots had finally connected at once. It was definitely worth a week-end cartoon project. I hope you make T-Shirts and Mugs out of it ! Send me pics.

(Also if you could grant me upload access to Dribbble, that would be very helpful https://dribbble.com/eloone)

Links:

What does git-rev-parse do?
http://stackoverflow.com/questions/15798862/what-does-git-rev-parse-do