I recently graduated from Iowa State University and began my career at DISTek, and during that time there is one thing that I notice engineers hate doing: documentation. Despite being loathed, it’s widely believed documentation is one of the most important things in software development. I always strive to see that code my teams and I have worked on will be well documented in some form or another. I, especially, run into problems with code that is developed as a library (a set of functions and data structures).
When I use a software library, I look for a concise description of all the functions and structures I will be required to use. Often, I encounter software that does not provide this. If I’m lucky, it will provide something like a simple user guide that serves as a good introduction, but lacks the kind of detail I mentioned. The guide might discuss a few functions, but the library has many more that are never even mentioned. The last thing I want to have to do is dig into the source code to learn what functions I have available to me. Often this isn’t even possible, with many libraries provided as a compiled file that gets included in a project.
When writing documentation for such a thing, I look at something like the Unix man pages for inspiration. These represent a very complete, yet concise, description of various functionality. The functions and structures to be used are presented first. Detailed information is provided, but it is presented after a brief overview, in such a way as it does not get in the way of someone who does not need it, and instead, is using the documentation as a reference.
The most important thing when writing documentation is to keep it brief. Long-winded technical discussion is important to have for those that want or need it, but my experience tells me that few want it or will even utilize it when they have it. Engineers most often want a reference. Something that they can use to look up what they need without getting bogged down in textbook like writing and information they don’t need.
In conclusion, if you make it too difficult to get the basic information, readers will simply stop reading and try to figure out what they need to know some other way. It saves a lot of time and a lot of headaches if the author of the documentation would have presented the information in a better format. Again, the two most important things I’ve seen are to be concise and to present only the essential information in the foreground. Detailed information is great, and often necessary, but is better as something a reader can continue to if they want more. Nobody wants to read a textbook cover to cover in order to develop an application!
