Documentation

May 22, 2011

Over the past twenty years I have read countless technical books, documents, help files and web pages searching for clues on how to work with numerous technologies and development tools. Is still amazes me after all these years the lack of consistency within the development community and within even specific sites on the process of documentation.

The ability for a project or technology to succeed both in the short and long term often can rest in the documentation. Giving other members of the team, or those who come from outside the development of the specific item information on how to use the technology is paramount to it use and acceptance as a tool to be widely used. I have frequently heard the phrase; "The code is the documentation." While commenting the code can be helpful and should be done (to excess!) it is not the documentation. Proper documentation of a technology should consist of at least the following:

A short description of the reason/purpose of the technology.

The date of creation and current version details.

Copyright, patent info and license details.

Writing credits. (If films and books get credit, why shouldn't we?)

Code samples.

I believe documentation suffers for a variety of reasons; I think that the developers who are writing the code are often under pressure from management to get this project done asap, or sooner. I can't count the number of times I have been asked how long a project will take to complete before I have even been given specifications. I believe this is because our industry is relatively new and there is a disconnect between developers and management. In the last decade I have seen this get better as more developers have risen into the ranks of management, usually through the role of Project Manager. The lack of foresight causes so much more wasted time at later stages of the process. Again, the number of projects that I have come into at later stages of development that had zero documentation is upsetting and, imo, criminal. (OK, so "criminal" is a bit harsh, but I think you're bright enough to get the idea.)

Another issue that I believe is an issue with the documentation is that those who write the code are too close to make good judgment calls on how to properly, and concisely state what the code does and how to use it.

This bring me to a big point; Code Samples. I have seen good code, really, I have. And it is littered with comments. The header is commented with how wrote it and when, the body of the function has numerous comments about what is supposed to happen and why something might fail, and the details about what is done to avoid specific or even unknown failures.

I once read a book in about 1993/94 called Visual Basic Database Programming and it contained only one and a half paragraphs about tables and joins. I understand that the mid 90's are the dark ages compared to where we are now, my point in this rant is to insure that in 10 years time we make the leaps in technology and its ease of use that should be occurring and to make it easier for me and you in our projects.