Whether you are fashioning your C-language SDK in MS Word, or crafting a collection of .NET assemblies in an automated documentation tool, such as Document! X, provide your users the convenience of an abstract before each code sample.

As the blurb on a book jacket, the outline or abstract provides an overview of the work the example code performs and informs the user of its relevance to the task at hand--in short, gives her safe ground and invites her in.

Hold on! Why bother? Certainly, the geeky user can get by without the abstract, and content herself with the few comment lines inside the example...

Considered from a professional viewpoint, this approach is wanting. Commercial product that it is, an SDK must be fully capable of providing users all they need to accomplish the tasks they face, both in terms of the tools it provides and in terms of the documentation that accompanies the tools.

Next blog: using Doxygen to tack an abstract onto a code sample.