"techdocs" idea

[Derek Atkins]

hi,

Jon Lapham <lapham at extracta.com.br> writes:

> There have been two requests for me to submit web pages to
> www.gnucash.org.  The translators howto and the detailed instructions
> on installing gnucash.
> 
> This got me to thinking (watch out).

uh oh. ;)

> Why not keep a "techdocs" directory in gnucash-docs in which these
> types of things are maintained in xml format.  Then, occasionally, we
> can press HTML versions for the web site, and text versions to place
> in the various locations of the source code (such as docs/).  Building
> these things do not need to be a part of the build process, so nothing
> complex to setup.  These documents should not (I think) be available
> in the gnucash help system, they are there just for the convienience
> of the developers.
> 
> What do you think?  Stupid idea?

I have no objection with the xml -> html for the web site, but I
do have objections on xml -> txt for the source tree.  IMHO the 
source docs are for developers and should be easily grokked by
developers.  I know I don't think in XML, and I don't mentally
parse XML as easily as I parse raw ascii english text.  So I'm
much more inclined to read/write techdocs in ascii -- especially
when most of it is just meant for notes to myself for years down the
road (or other developers to get inside my head).

> Advantages: 1) centralized location for all tech docs, no duplication
> of effort. 2) multiple output formats (.ps, .pdf in the future
> too!). 3) easier to work with in terms of internationalization.
> 
> Disadvantages: have to write in xml, rather than ascii text.

I consider this a major disadvantage considering the purpose and
audience of the source-tree docs.  IMHO, this disadvantage far
outweighs the advantages.  Another disadvantage is the new dependency
you create, where the gnucash source tree now depends on gnucash-docs,
and you have to maintain coherency of the internal documentation.

I do agree that "user servicible" docs should live in xml format in
gnucash-docs and be pushed out.  But the majority of documentation in
txt files in the source tree is NOT user servicable (except, perhaps,
the README -- but again I don't want to create this backwards
dependency).

-derek

-- 
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       warlord at MIT.EDU                        PGP key available