Dr. Dobbs Journal hosted Jim Dempsey's blog The Lost Art of Writing Good Documentation, where he points out the shortcomings of generated API documentation. Good function documentation, he argues, includes everything the reader needs to know:
- #include file list as appears in an application
- Function prototype
- Compatibility table
- Sample of function call
- Descriptions of required access flags
- Descriptions of optional access flags
- Descriptions of mode flags used when creating a file
- List of return values
- List of related library functions
- Complete working example program using the function
What he most wants -- and what is so miserably hard to provide -- is comprehensive coverage that minimizes the need for readers to continue searching and clicking off the page to gather the critical bits of information they need to master a function. Worse, he says the open source project he sites requires readers to have open legacy documentation for simultaneous reference and comparison (which is about as user unfriendly as documentation can get).
The takeaway here may be that we should configure our automated documentation tool templates to generate more placeholders for the information that needs to be human-supplied later, and let those placeholders be the goads to drive us to exert the effort to give readers what they need. The goal: high-value documentation that saves developers hours of tedious research on new functions.
Everything is a balance; every shop tries to allocate just enough but not too much time to documentation. The temptation is to do less and wait for feedback, asking for more. The danger is that this presumes the SDK users, now disgruntled, will engage enough to do so.
