If we're talking about changing things, here's my totally unreasonable and
unrealistic documentation system wishlist.
- Markup: should look as much like a "plain" text document as possible, so that
it's easy to read and edit the documentation without having to continually
process it to double-check that it's going to come out right. Nice-looking
tables are essential. Bonus points for syntax highlighting mode for Emacs. An
example of IMHO *lovely* markup is reStructured Text.
- Conversion: should be able to convert the *same* sources to man pages and
DocBook XML, and onward to XHTML / HTMLHelp / PDF etc. This is essential so
that people who want to contribute to any gEDA documentation only need to learn
one markup syntax. An example of IMHO excellent conversion support is
ASCIIDoc. The git docs use it especially effectively.
- Version control: reference docs should be maintained in-tree so that each
branch (e.g. stable and unstable) has its documentation alongside it. Not so
fussed about things like "getting started" guides. It's really good for
developers to be in the habit of updating docs in the same patch as changing
behaviour. Lots of systems can support this. Would need a "docs coordinator"
or something to assist people who want to help with documentation work but
don't have git expertise.
Peter
--
Peter Brett <[email protected]>
Remote Sensing Research Group
Surrey Space Centre
_______________________________________________
geda-user mailing list
[email protected]
http://www.seul.org/cgi-bin/mailman/listinfo/geda-user
