I remember the original “Inside Macintosh.” I actually still have the loose-leaf binder version of “Inside Macintosh” that shipped with System v1.

The original Inside Macintosh documented the “Macintosh Toolkit” (the acronym “API” wasn’t in common use then), and, aside from two introductory chapters–one which described the OS and one which documented a sample application–each chapter followed the same formula. The first part of the chapter, consisting of from 1 to a dozen pages, would provide an overview of that toolkit. For example, the “Resource Manager” overview describes what resources are, how resource are important, and how resources are stored on disk. The second part of the chapter would always be “Using the XXX Manager”–giving examples which generally followed the pattern of how you initialized that manager, how to create or manipulate fundamental objects, how to dispose of fundamental objects, and how to shut the manager down. This would consist of the bulk of the chapter. And the end of the chapter would be a summary–generally a summary of the header file for that manager.

It always struck me that such a model was a great way to handle documentation. Start with a 1 to 3 page introduction to whatever fundamental module you are documenting–a “module” consisting of a logical unit of functionality, which could consist of several classes. Then launch into a 20 page document showing how you use that module: how you start it up, how you use the major features, how you configure the major features, how you shut it down. And give snippets of code showing how these are done.

And the summary should point to either the generated JavaDocs or HeaderDoc generated documentation giving the specific calls and specific parameters for each call.

What is interesting about such a model is that it should be fairly easy to write for the technical person creating the toolset: he knows how he wants his class set to be used, so he should be able to craft documentation describing how to use it. For a class which presents a table, for example, the developer has a mental model of how tables are displayed: a delegate or data source is created which responds to certain calls and is attached to the table.

It has always been my opinion that writing code is simply one part of a multi-step process which ultimately results in your code being used. After all, isn’t the whole point of creating code is getting people to use your code? Developers rail against “lusers” who refuse to learn how to use their computers–but I suspect it’s because developers know their fellow developers are more likely to work through the source kit than the average person, and it allows them the excuse not to write the documentation they should write.

Your code isn’t finished until it is well documented. And complaining about people who are confused without good documentation is simply shifting the blame.