The Programmer community is often subject to many uncalled for criticisms. That they are socially challenged, that they dress shabbily, that they are more comfortable with machine than with humans, that they cant start a conversation with strangers and so goes this list. Somewhere in this list is the criticism that programmers don’t document enough.
I think there are at least three reasons why programmers are reluctant to document. But before that, let me set the context appropriately. Technical documentation can be broadly classified as documents for users (user guide) and documents for fellow developers (design doc). Programmers are OK with scribbling a basic user guide. I mean, they would be decipherable and a documentation person could convert those scribblings into a neat user guide. So far so good. Of interest in this post, is the other kind of documentation, the Design/developer documentation.
As I said earlier, there are at least three reasons that lead to this. One is a productivity oriented reason and other is habitual or behavioral and last concerns job security.
Design or developer documentation describes how the software works or supposed to work. It is written with the foresight that in future a new comer would be able to read the document and be able to understand the software better and ease his acquaintance with the software for any subsequent maintenance of the same. But the catch here is that the ultimate truth lies in the code. The Ultimate truth lies in the code and nowhere else but the code. If the documentation needs to be up to date and reflect the reality, then it should be detailed enough and abstracted to an accepted limit. But even then, it would be quite a detailed documentation. So the smart programmer thinks “In the time I take to write this document, I can as well finish the coding”. This is a very serious line of reasoning. Both documentation and coding involves the same prerequisites like clarity of thought process, sequencing of chapter/sections/programs to be written, code/document organization, modularization and so on. So there is really no motive to do the similar stuff twice. Once as documentation and again the same as programming. In fact, it is this line of thought that has given rise to tools like java doc, which apart from capturing the API contract also captures as much documentation the developer can provide so as to eliminate the drudgery of having to create detailed documentation.
OK I have written enough. To put it in a nutshell Reason 1 : Programmers don’t ( and won’t ) document because it nearly takes as much thought to code. And programmers are taught to reduce/eliminate redundancy !
The next reason is somewhat related to the previous one. Programmers just don’t read documentation. Now why they behave this way is a subject matter for another blog. But for now, take it that Programmers are too lazy to read documentation. They almost always rely on the Code editor’s intellisense and autocomplete features and meagre documentation that can be found in javadoc and the like. Given this nature, it is quite natural for the programmer to think “Why write document that would anyway not be read by any fellow programmer”.I guess this one is easy to grasp. Reason 2 : Programmers don’t read documentation and therefore, they don’t write one either !
The third reason is interesting. Complex software is really hard to understand by looking into the code. Agreed, the Ultimate truth is in the code. But many a times it turns out to be a needle in the haystack kind of a thing. Should a neat documentation exist, then it is as much easier to find the needle in the haystack. It also means that anyone could just read the document and start figuring things out. So the programmers feel that better the documentation they do lesser the job security. One way to make themselves dispensable is to write bad or no documentation at all ! Reason 3 : Bad or No documentation would make the Programmer indispensable.
In my career as programmer spanning 10 years, I have rarely come across useful developer documents (leave alone fantastic ones). This is the situation in big and small corporates that boast of smart people. Contrary to this, I find documentation in Open Source projects to be of good quality (Of course there are exceptions). This is written by the very same kind of developers (not dedicated documentationists ). Looks like there is something beyond the above reasons that could make a good developer come up with quality documentation.