There is wide agreement that in an API (SDK), perhaps the most vital element (and the one the uninitiated programmer always looks for) is the samples. So what is the writer's role in all this? A technical writer must always come to grips with the problem and the proposed solution, from the customer point of view.

Representing the users, the technical writers, then, should be intimately involved with every word in the documentation set. And if the documentation set must include samples, the tech writer should create those too.

“I have documented methods in my C++ class but they are not appearing in the HTML output.”

Surprised?

Doxygen ignores the documentation of global entities (like functions) if the file that contains these is, itself, not documented.

“To document a member of a C++ class, you must also document the class itself. The same holds for namespaces. To document a global C function, typedef, enum or preprocessor definition you must first document the file that contains it (usually this will be a header file, because that file contains the information that is exported to other source files).

I had experienced TechWriter Concussion in the past – you know, when expectations of management collide with the actual material and your head is somewhere in-between. My first day on site at ABC Telecom Solutions (an imaginary name), Czech Republic, employer of more than 900, was classical in that sense, only on a much grander scale.

This was the scenario:

The hallmark of a well-conceived SDK is the quality and range of the examples you supply with it. The examples are the starting point for the vast majority of programmers. That's where they stick their big toe in and test the water.

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.

Today's piece follows yesterday's and describes how to tack on abstracts to examples using Doxygen.

1. Prepare a text file that contains only abstracts and associates each abstract to the example code it describes. Let's call it examples_doc. The example shows two abstracts for two examples:

/*! \example register.cc

There are two possible scenarios when registering command line arguments.
Both are useful but are intended for different work flows:

• The first is simpler and faster. It is suitable in cases where