Documentation format

From: VanL <vlindberg_at_verio_dot_net>
Date: Wed Aug 06 2003 - 17:12:48 CDT


After reviewing the list postings about documentation format, I have the
following comments:

1. I concur that the documentation format be something that is
human-readable in a text editor. Not only does this make the
documentation easier to read -- no special programs required -- it also
makes it easier to write.

2. APT appears fine; however, the only implementation I was able to find
was in Java. If we decide jython is a suitable implementation language,
I would have no problems using APT. However, I would prefer a
documentation format such that the docs can be automatically built from
the source tree without the invocation of a separate language.

3. reStructuredText (or even the original structured text
implementation, removed from Zope) has many of the same qualities as
APT, and might bear some looking.

4. I would personally prefer using something like APT or StructuredText
to write the documentation than something like XML, if for no other
reason than writing XML of even moderately complex dialect can be a
pain. I would rather process something simple into a more structured
format, rather than making something complex and then processing it down
into something simple.

5. Personally, I have been writing using an outliner and exporting to
RTF, which is a reasonably capable and cross-platform format. However,
I have no problems using another documentation format.

= The content of this message, with the exception of any external
= quotations under fair use, are released to the Public Domain
Received on Sun Aug 31 23:17:02 2003

This archive was generated by hypermail 2.1.8 : Sun Aug 31 2003 - 23:17:17 CDT