[Webware-discuss] Documentation

[Joel Lawhead]

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: [EMAIL PROTECTED]