[Webware-discuss] Documentation

[Joel L. <jla...@nv...>]

It sounds like there are two different needs being discussed for
documentation.  The first need is an easy way for core Webware
developers to quickly document the software as it develops in an
organized, complete but easy to use way that doesn't require a lot of
effort. Second is a formatting system to make public documentation that
will be accessed by new users which looks very pretty, is highly
organized and cross-referenced, and well suited for publishing to
different formats (HTML, PDF, text, etc.). You won't find a
documentation tool that covers both needs well.
 
I agree with Ray in that there should probably be a simple documentation
development cycle in which initial docs are produced by core developers
using something easy like reST with simple code examples and then passed
on to a documentation team that can organize the documentation, place it
in a transformable format, add more code examples, and then produce
documentation properly in different formats adding features like user
comments and indexes.
 
The simple markup language used by developers only needs to support:
Headings, sub-headings, code-blocks (html, python, psp syntax), and
probably hyperlinks (did I miss anything?).  From that type of markup
any type of formal documentation could be derived by a team focused on
that task.  It would probably be a good idea to structure the
documentation in XML at some point just because of XSLT. But XML is
probably too taggy and structured for the simple documentation format
and would be the job of the documentation team.
 
Including myself I've counted three volunteers to be on the
documentation team so far in this discussion.
 
Any ideas?
 
-- Joel
 
Joel Lawhead, Web Application Developer
NVision Solutions Inc, www.nvisionsolutions.com
Phone: 228-688-3951, Fax: 228-688-3843
E-mail: jla...@nv...