Documentation for the release

[byron]

> One other reason that (IMHO) documentation lags is SGML formatting. Sure,
> it's not difficult, but it's one more hurdle for the person who doesn't do
> it often. 

i second that.  setting up the docs build envrionment is a pain (impossible on
windows).  while i have landfill access, it's pretty slow at times.

> Fortunately, one way in which 'docs are not like code' (at least so far as
> Bugzilla itself is concerned) is that code is only released at specific,
> discrete intervals. The Bugzilla docs are updated www.bugzilla.org (which is
> where I'd bet that >95% of English-speaking people come looking for
> documentation) happen every fifteen minutes. When something gets checked in
> to the docs, it is almost instantaneously available to the public at large.
> This means that we do not have to make it through a specific window before
> it closes on us.

i'd agree with that if the docs weren't bundled with the product.  if i
download a tarball that includes a manual, i'd expect it to be up to date,
with updates only occuring with a new versioned release of the product.  i
also don't think it's unreasonable to expect that the online docs for 2.18.0
always match the docs in the 2.18.0 tarball.


the other option is to only include the quickstart in the tarball, with a
reference to the bugzilla website.  then any documentation updates *will* be
instantaneously available to the public.


throwing ideas "into the wind" (with very little forethought) would it be a
good idea to use html as the base document format, and generate text and pdf
from the html?


begin-base64 644 signature.gif
R0lGODlhbQAHAIAAAABPo////ywAAAAAbQAHAAACfAxuGAnch+Bibkn7FL1p
XgVl4Ig1jjlZRoqybgun2Cur5uOunq7u/Ipq7WIyIc7XG9JquEgumPzdlhTf
h0O83kDJaXEm8mRHwXKJy5sac7qYOpT+gtv0n+0ujQOfdqh16caWt0foBViH
N1PRMXimiLUGt3ElVimlgbllWAAAOw==
====