[Gllug] Interactive Documentation.

[Peter Childs]

On 21/08/06, Richard Jones <rich at annexia.org> wrote:
> 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?

Depends Clue level is extremely low its users documenting company
protocol plus how to use the computers to there best advantage,
actually how the code works is of lesser importance.

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

No it needs to closely track how this place ticks and how this relates
to our in house code.....

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

I tend to agree with you, but I need something that anyone can update
so it is likely to be correct and will not age if its not easy to
maintain I can promise you it will not be!

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

Why is it that Linux users always seam to go for text editors I'm a vi
fan but if you want the man in the street to use it you NEED to go for
WYSIWYG approach I think if I spoke to the office staff about it they
would suggest Word (and I would give them openoffice which is not
really suitable for large documents of this style)

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

Yes I've seen some very good developer documentation done in this way
but not usually user documentation and I also need to document more
than just the code. In a user centric manor.

Peter
-- 
Gllug mailing list  -  Gllug at gllug.org.uk
http://lists.gllug.org.uk/mailman/listinfo/gllug