[Gllug] Interactive Documentation.

[Richard Jones]

On Mon, Aug 21, 2006 at 08:00:35AM +0100, Peter Childs wrote:
> I need to produce a relatively large set of internal documentation at
> work Manual Style I'm thinking a wiki might work well as some of the
> details I know nothing about and am not the best person to write.
> With so many similar tools about I'm trying to work out which is the
> best and easiest to us.
> 
> The following requirements come to mind.
> 
> 1. Good quality printing as someone is more than likely to want it in
> print form from time to time.
> 2. Easy to maintain and keep up to date as things change.
> 3. Easy to integrate with our computer system that's Qt based so I was
> looking at Qt Assistant. but I do need something easy to update.

Some questions:

(1) Who will create and maintain the documentation?

  - What is their level of clue?
  - How extensive will their edits be?

(2) Will the documentation need to closely track changes in the
    code?  [It sounds like it will from your description]

(3) Is this a discourse (like a manual) or a collection of facts,
    or perhaps a mixture of both?

Wikis can be used for certain types of documentation but you should be
aware of their limitations.  They tend to be well suited towards
simple collections of facts.  It's labour-intensive to turn a wiki
into a printed manual.  And wikis exist in a world of their own which
means they cannot be auto-generated, nor can they be auto-verified
against (say) a large body of source code.  (Well, at least not
without deep understanding of the backing database and a lot of glue
code).  And although they usually have a concept of "versions", this
is only a very primitive form of version control.

If you want to generate a manual, *and* all of the potential editors
are clueful, then you'd be hard pressed to beat DocBook/XML as a
format, with a standard version control system and simple text editors
to edit (I recommend Aquamacs on Mac OS X - a fantastic version of
Emacs for editing XML docs).

If you're documenting some large codebase, then by far the best
documentation is whatever literate programming tool is provided by the
language (eg. POD, javadoc, etc.).  Keeping the documentation in
comments next to the code usually ensures that it's up to date, and
you can reuse your existing build process and version control.

In some cases (eg. tutorial + reference manual) it may be necessary to
combine approaches - say DocBook for the tutorial part, and some
custom munging to auto-generate DocBook from code comments for the
reference part.

Rich.

-- 
Richard Jones, CTO Merjis Ltd.
Merjis - web marketing and technology - http://merjis.com
Team Notepad - intranets and extranets for business - http://team-notepad.com
-- 
Gllug mailing list  -  Gllug at gllug.org.uk
http://lists.gllug.org.uk/mailman/listinfo/gllug