[sclug] Re: Documentation

[Simon Huggins]

On Tue, May 06, 2003 at 10:12:55AM +0100, pieter claassen wrote:
>      8. Documentation is being done in POD for the software and a wiki
>      for user docs which means it is mainly text that gets marked up
>      automatically. The wiki is installed locally with the application
>      and there is a CGI script to automatically update the
>      documentation. I am using twiki which is not bad at all.
>      However, I am not totally sure that this proprietary markup is
>      the right way to go. The main issue is that if you ever need to
>      access the content directly for whatever reason, then you can
>      read it in any editor, but you will need to write a parser to
>      make it look a little better. However, it is possible write HTML
>      directly in the wiki and I might consider that. The problem with
>      documentation is that I need something that makes it easy to
>      cross reference, produces HTML and is portable. A simple HTML
>      editor might work better. Documentation is still a little
>      headache.

I fell in love with Wikis a while back.  One nice thing in particular
(apart from the obvious sharing the editing stuff) is that it is fairly
easy to mark up without having to actually write HTML and it does the
whole content without style thing very easily.

You mention needing a parser and I think this already exists in Perl
called CGI-Wiki written by someone I know though I don't know how much
it parses nor how well.


Simon

-- 
... "A lie, Mr. Mulder, is most convincingly hidden between two truths" -
    Deep Throat