Documentation

Working code is all very well, but nobody will use it if the documentation is absent, obscure or wrong. I want people to use the programs that I write, so I make sure that I find time to write good documentation for them. I prefer to write documentation using Docbook XML, because it converts easily into a wide variety of common formats, from PDF & HTML to Unix Man pages.

Here are a few examples.

Man page

Unix-style man pages have a terse style that is intended to convey the maximum information in as little space as possible. Here is my man page for omniEvents (8).

Tutorial: How to Write an Event Service Client

When writing a tutorial, it's important to have a clear conception of the target audience. In this case, the reader is expected know what the Event Service is, and to have a basic understanding of CORBA. The goal is the talk the reader through the choices they will have to make, and warn them of the pitfalls they may encounter. I try to present self-contained 'nuggets' of information, that will be useful as a reference as well as to those who read the whole thing from the beginning.

Tutorial: Build and Install omniEvents

The goal of these instructions is to provide newbies with enough detail to successfully install omniEvents. There is a common 'pattern' to installing software that uses Autoconf, and it's important to emphasize that pattern here - Hopefully an old hand will just glance at the instructions and know what to do.

The example reiterates the instructions, and distills them down into just a few lines.

ASCII Art: Detailed description of OmniEvents::EventChannel

A vital skill in the modern age.

Portfolio Multithreaded Programming Unix Daemon & Windows Service Windows Registry GNU Autoconf Documentation Web Design Java Python

©2005, Alex Tingle. This work is licensed under a Creative Commons License.
Permission granted to copy but NOT TO MODIFY this document.