Documentation

[Jon Wilmoth]

As I submitted the first patch for the "customizable terminology"
contribution, I'm willing to help with the documentation effort.  How
should I submit this info?

I think the move to the xml definition is great and will lower the
barrier to entry for following up code contributions with documentation
so others are aware of the functionality and benefit fully from it.  I'd
also be willing to help develop the xsl stylesheets for at least the
HTML and Text versions.  I'm not sure PDF can be generated with simple
XSL.

-----Original Message-----
From: developers-owner at bugzilla.org
[mailto:developers-owner at bugzilla.org] On Behalf Of David Miller
Sent: Tuesday, January 27, 2004 6:23 PM
To: developers at bugzilla.org
Subject: Documentation

Reminder:  the default assignee for Bugzilla documentation bugs is
documentation at bugzilla.org, which is a dummy account on
bugzilla.mozilla.org.  If you would like to help with docs, please go to
your preferences and add that account to your watch list.  I'm pretty
sure
I heard from no less than 3 people who volunteered to help (outside of
myself), and there's a total of 3 people watching that account, which
includes myself and the ircbot. :)

In other news...
   I'd like to propose completely removing the HTML, Text, and PDF
versions
of the docs from CVS.  Under my plan, the website will automatically
build
those directories upon pulling changes to the xml directory, and the
tarball build script will be changed to build the docs after checking
out
of cvs prior to rolling the tarball.

Reasons for doing this:
1) those directories are already off-limits for direct modifications in
cvs
anyway, they're required to be generated from the XML before checkin
2) every time they're regenerated, it "modifies" every single file,
which
results in a HUGE chunk of space in the cvs commit log on bonsai.

Cons:
1) If someone checks in an XML change that doesn't validate, it'll
likely
take out the HTML version of the docs on the website if they don't fix
it
within 15 minutes.
2) People checking out of cvs who don't have docbook set up won't have
the
html and text versions of the docs to read.

Pros:
1) XML changes would be immediately reflected on the website instead of
having to wait for someone to regenerate the HTML and check it in.

Any comments?  Any other pros/cons to this?  Does this sound like a good
idea?
-- 
Dave Miller      Project Leader, Bugzilla Bug Tracking System
http://www.justdave.net/             http://www.bugzilla.org/
-
To view or change your list settings, click here:
<http://bugzilla.org/cgi-bin/mj_wwwusr?user=jwilmoth@starbucks.com>