How do you document sample programs?

Question

Let's say you have to [write from scratch, rewrite, refactor] a sample program illustrating how to do something quite specific with some middleware/SDK/library, or maybe just some programming technique, all of this for learning purposes.

How do you document the sample programs?

I'm asking that because I found that even with complete rewrite of some SDK sample, even with extensive commenting, I feel the need for some high level meta-documentation or comments, or whatever you can call it - some overview page describing what the project is about.

• README file for every sample program can do the job, but they don't have the pretty formatting of the wikis, for instance.

  • Pros: Simple
  • Cons: Too simplistic; Not part of the source files;

• Doxygen comments: Do you think that it is possible to write the doxygen comments in a way that each project outputs a Doxygen-generated 'main' page with the

  • Pros: Part of the source files; (If possible) Useful hyperlinked documentation main page.
  • Cons: None that I can think of

• Version Control System + TRAC ticketing/wiki system: Since I use Subversion for my projects, it seems to me that installing TRAC alongside the SVN repo can do the job of documenting the sample programs, but I'm not sure whether this is an overkill because I haven't use TRAC + Subversion in a working environment and I'm not sure of the workflow of usage of TRAC + Subversion, what is usually written in the tickets, wikipages, how all of this is 'connected' to particular revisions of the programs that need to be documented, etc.

  • Does the (possibly wild) idea of using TRAC in addition to Subversion repo make sense? Or I'm completely missing the point and the basics of the workflow with SVN + TRAC?
  • Pros: Feature-rich
  • Cons: (Maybe) an overkill for setup and maintenance

Answer 1

I tend to prefer documentation in the source. I think that this increases the chances of it being found and being maintained. In my Java world you can produce quite nice JavaDoc that can be extracted from teh source, including package-level overview material.

I would add explanatory overview material there, or in the primary entry point to the applciation, where my "main" is if I have one.

A README.txt actually in my source directory will also make it into my SCM so that can work too, but I just prefer some form of unity with the rest of my program documentation.

Answer 2

If possible, think of the most common scenarios and provide simple (ideally separate) samples for each of them. I find it is often very frustrating using a new SDK because the samples do one or two very specific things that are unrelated to my needs, so I am left in the dark about how to get started.

As to documentation, I'd start by ensuring the sample code is in a good clean coding style, and well commented (both in-code comments and DocXml/Doxygen function comments that can be read while coding and/or extracted to an externally readable format). This in itself should be enough to allow a good programmer to understand the samples (i.e. class comments should describe how/where/why the class is used, not just contain the name of the class with spaces between the words!)

Then I'd add a quick-start guide and/or overview of the sample - pdf would be a good format because it allows you to use nice formatting and is easily read and printed. You are right about overviews being useful. Think of it from your end user's point of view: "I've never seen this SDK and I want to do XYZ. Where should I look first, and what key concepts do I need to understand?".

The main thing to bear in mind is that the guy trying to use your SDK has never used it before, so the explanations should not assume any prior knowledge, and should cover the basics. This is where most SDK documentation falls down: The author is an expert in using the SDK and they leap in at a level that is already way above the understanding of their readers. Or they document everything so the end-user is swamped with information about a thousand API calls, but has no idea which one to call first to just get started. Often a single sentence can save somebody spending hours/days working their way through samples/documentation trying to figure out how things work.