Documentation for the release

byron bugzilla at
Sun Jan 16 13:56:30 UTC 2005

> 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 (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

More information about the developers mailing list