Incomplete documentation is the bane of any project. Yet in this age of word processors, automatic documentation generators, and CD-ROMs, getting the details down in humanly readable form is no better than it was twenty years ago. And, the cost of this problem keeps on rising as more people depend upon it.
Many great designs started out on a paper napkin. But many of them stayed there or got lost along the way because the important details were stuck in someone's head, written down on a notepad sitting on someone's desk, or spread across a CD-ROM and some printed documentation.
I know that most of you are nodding in agreement. So why bring up such an obvious issue? I recently received a software development package that will remain nameless. It implements technology that has been written about for many years. Its documentation is very polished, with loads of white papers and detailed functional documentation.
Unfortunately, the heart of the details of the implementation can only be found by diving into the source code. This can be an enjoyable exercise for some when time allows, assuming that the code is well written and documented. While this was the case, the fact that detailed specifications were not available outside the source code made the job of analyzing and using the software a much more time-consuming task.
Good documentation is critical to using a software package or building an SoC. It is even more important when trying to support, debug, or make enhancements, especially when the original developers or designers are unavailable. Engineers and programmers change jobs so quickly that often the third generation is the only source of information, along with whatever written documentation was created.
Documenting one's work is never as much fun as doing the work, though. Part of the problem is that tools for creating good documentation are so limited. This is especially true given the advances from Internet technology, such as hyperlinks and the expanded use of audio and video. Very little of this makes its way back to developers.
The tools of the trade are much as they were 50 years ago. Comments in source code, if they exist, are often the only place where definitive information can be found. Similar problems arise with high-level hardware designs that use hardware-definition languages like SystemC. It's a great tool for designing, but it's no better at documentation than using C with a text editor.
Meanwhile, most managers and project leaders value documentation less than quality assurance in terms of priorities. The latter has risen significantly in importance in many organizations, yet documentation normally winds up at the bottom of the barrel.
The roots of poor documentation can be found in the way engineers and most professionals are educated. Taking good notes in class is a highly regarded skill. But how many teaching institutions try to train students to turn this information into something others can utilize? The publication of technical papers is the answer that many will point to, yet this is typically left to graduate-level work. In many cases, these papers provide only a cursory overview of work that is much more complex.
If you think that this issue is not as bad as I make it out to be, then consider the last technical presentation you saw or the last technical document that you had to use. How much information did you get for the amount of time you invested? Also, were your questions really answered?
I am sure that everyone will be interested if you have some good solutions.