[Gllug] Interactive Documentation.

[Mike Brodbelt]

Peter Childs wrote:

> Why is it that Linux users always seam to go for text editors.

Perhaps because we've used the WYSIWYG options, and they just don't work
very well. If you want to write a letter, then Word is adequate. If you
want something typeset properly, then it rapidly becomes painful. Just
look at any professional typesetting system - at most they provide a
WYSIWYG wrapper around a markup (often XML). Many provide no wrapper at all.

> 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

If your users will only accept Word, then your final result will be
poor. There's no point whatsoever in specifying a list of requirements
(as you did in your original mail), then mandating a system which cannot
fulfil them. You have two choices - accept poor documentation, or choose
a better solution, and attempt to educate your users as to why it is
better. If you show them how you can easily generate HTML for the
intranet and PDF for print from the same source document, they might
start to get the picture. If you can demonstrate the advantages, people
will be willing to put in time to learn. Many non-technical people can
do a bit of HTML - other markup shouldn't be that alien a concept.

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

Go read the Samba HOWTO Collection - that's user type documentation,
reads like a book, and the full DocBook source is available in the
tarball. Or have a look at http://www.tug.org/tutorials/tugindia/ where
there's a lot of nice Latex tutorial material, with source, and HTML and
PDF outputs.

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