[Gllug] Interactive Documentation.

[Richard Jones]

On Mon, Aug 21, 2006 at 01:33:11PM +0100, Peter Childs wrote:
> On 21/08/06, Richard Jones <rich at annexia.org> wrote:
> >(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.

Sorry Peter there seems to be some sort of email filter which is
removing full stops and capital letters from your messages.

Anyway from what I can gather you mean, you may have problems teaching
people the "wiki markup" used by common wikis -- I know we've had
endless problems in this area.  Some wikis are better than others in
this respect.  MediaWiki in particular now has a whole range of
client-side tools which are to a greater or lesser extent WYSIWYG-ish.

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

Choose a wiki which has a coherent database format which is easily
understandable and updatable.  Then write glue code which keeps
certain reference pages up to date from code comments ...?  It's going
to be tricky to implement.

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

I'm having the misfortune at the moment of collaborating on a book
using Word's "track changes" feature, which is a sort of version
control abomination.  It's lame that this is the most "powerful"
document control that most people have access to.

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