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.

This is purist theory. Practically, this is not a requirement.

In all my time as an API writer, I was never once required to write an example myself. Moreover, I would not trust myself to do so. I have learned several programming languages, have worked daily in software engineering environments for over 15 years, but still wouldn’t say, “I can code in Java!”

My approach to documenting an SDK is to represent the user, guide the engineers through the topics a user would seek and have the engineers provide the rough source material. That is true for the overview, the reference material and the examples. In encouraging the engineers to come up with examples, I point them to the same tests they developed to QA their own units, or to code developed by Integration teams in the field (more often than not, SDKs grow out of customized APIs developed for specific users). The result of this approach is true-to-life samples that demonstrate broad applicability and that are accessible–again–to the users.

So, for the purposes of API documentation, I would prefer being a programmer-tech-writer to being a tech-writer. Notwithstanding, even if I were a programmer, I might defer to the field engineer or technical support engineer for accurate, practical and applicable samples.

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).

In other words, there must at least be a

/*! \file */

or a

/** @file */

line in this file.

See:

http://www.stack.nl/~dimitri/doxygen/

docblocks.html#structuralcommands

This was the scenario:

Mandate: The documentation professional (that’s me) will produce a set of English-language product documentation for a first-release complex platform. The set (comprising an estimated 50 notable deliverables) will be ready for release in six months.

Software availability: Modules are produced independently in R&D centers in Bratislav, Minsk, Moscow and Prague. Modules “speak in different GUI languages and styles” and are “not on talking terms”.

Existing documentation: a heap of engineering notes in English, Czech and Russian, deep inside the Mail Server.

SMEs: a multi-national group of disgruntled programmers, most of them (mis-)operating as integrators on remote sites around the globe (in Asia and Africa).

Writing team: Moshe and two engineering typists
Seasoned consultant, notwithstanding, I was overcome with hot flushes (even though I am only 43). Was the prospect of the couldn’t-be-done too terrifying, or too ghastly to contemplate? No, it was laughable, ridiculous. My gut told me “flee”. I feigned jet-lag. Where could I lie down?

I needed partisans fast, had limited time and budget, so I forayed into every group in STS, coaxing management to reassign talent “temporarily” and came up with the following group:
Genia, a Russian literature graduate from Novosibirsk, Siberia (seized from the translators group); the two resident engineering typists — both from the greater Prague area: Michal, previously employed as a snowboarding instructor and Zdenĕk, a humanities graduate; Saša, a Czech literature major who hailed from St. Petersburg, Russia (once a translator in the company); Dima, a delightful Russian, endowed with loads of good will and then manager of a company group portal; Hana, a real-life Bohemian, passionate dancer and Czech language major at Charles University, Prague (also a translator); Tanya, an erstwhile physician from Minsk, and recently employed at the company as a translator; Adam, a long-time expat from the USA, in his recent past, a dilettante restaurateur and legal editor; Geoff, a bright American college graduate with a Czech girlfriend; Rose, a sound and lighting technician, with excessive experience at rock concerts.

A motley group indeed, working in an environment hostile to technical writers (where are they not?) in a country where there is still no translation for “technical writer”. Yet, at the end of my tenure (Jan 2008), management declared the major accomplishment of 2007 to be “Documentation”!

How did we pull it off?

I injected a generous dose of Israeli thrift and improvisation into a group possessing a unique blend of post-Communist inexperience and a traditionally Czech delight for independence of expression.

That energy formula produced 50 deliverables and more, several times over: users guides, installation manuals, integrators guides, SDKs, operation and maintenance manuals, functional specifications and more, in Word, in PDF, in online help (using ePublisher), in HTML, in Help v2 for .NET programming environments (using Sandcastle), all according to an exacting style guide, using strictly defined Word templates, within a predefined review timeline. Moreover, as ABC Telecom undertook more challenging projects, the group learned to support translation and localisation efforts too. In short, each of them had become an accomplished technical communicator; each of them a rich asset to the company; each possessing an enviable resume.

The experience for me was exhilarating. During our fascinating journey together, I was given almost complete carte blanche to express my full complement of skills, knowledge, and experience as a trainer, coach, mentor, technical communicator and micromanager to a group of greenfield writers. Chutzpah and the 1989 Velvet Revolution had collaborated to leverage resources to attain un-dreamt-of accomplishments.

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
  users define, parse, and use command line arguments in the same source file
  (typically, in the main() function).

• The second method allows users to define the command line arguments in
  a library and to use it in any source by including the .h file where command line arguments
  are defined.

*/

/*! \example ScopesDef.cc

This example demonstrates:
- How to define \c IdAbsDA subclasses corresponding to different scopes.
- How to register IDs
*/

Ensure that the name of the example following the \example tag is exactly the name of the example stored. Referencing ScopesDef.cpp when the name is ScopesDef.cc will not produce the results you need.

2. In the list of inputs referenced by the INPUT configuration parameter, add examples_doc.
3. Make sure the EXAMPLE_PATH parameter points to the folder(s) that contain the examples.

Now run Doxygen and voila.

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.

Most programmers will be able to scan the example code and, with some basic comments, be able to understand what they do–especially if the developers have tested the examples and seen that they actually run (not always obvious). But if you document the examples and catalog them, you add an extra dimension that sets your professional SDK apart from the rest.

In a series of pieces, I am going to show you how to do some cool things with examples using Doxygen. Today’s describes how to generate automatic links from the programmer’s guide in your SDK (which includes the examples, in my view) to the dry class-and-method reference side.

Before I start, I am going to assume that since you are preparing a commercial SDK, you desire to expose certain classes and methods in your headers and hide others, meaning you have made the following Doxygen configuration settings:

HIDE_UNDOC_MEMBERS = YES
HIDE_UNDOC_CLASSES = YES

The meaning of these settings is that your output will show only those classes and methods that you have documented. I stress this, because links between reference and examples are only possible where you have documented the relevant classes and methods.

Now the process:

1. You don’t have to keep all the examples in a single folder. Doxygen can handle examples in several sources. Personally, I prefer to keep the examples for a single library in one location, reproducing the same tree structure for the folder, relative to its parent library. It’s less management overhead and eases the collaborative effort between writers, R&D and different teams within R&D.

2. Once you know where your examples are located, point to the location using the EXAMPLES_PATH configuration parameter.

That’s it.

Now, the documented #includes in your example code are hyperlinked to the headers. Calls to methods are linked to the description of the classes and the methods they contain.

An extra to end: to make sure you enable all the links you can, add a compilation warning to flag the files and methods you have not documented, like this:

WARN_IF_UNDOCUMENTED = YES