Documentation for the release

[Gervase Markham]

byron wrote:
> 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.

Well, the online docs for 2.18 should match the latest release of 2.18 - 
we don't do online docs by point release, only by major release. But, as 
we will only be updating it with security fixes, the content shouldn't 
change much.

I certainly agree that the docs should not undergo major reorganisation 
post-release, for the reason you gave. The 2.18.7 docs should be 
substantially similar to the 2.18.0 docs, such that anyone familiar with 
the latter can easily find what they want in the former.

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

I still think shipping docs is a good idea - some admins may want the 
machine disconnected from the network during the install (and, in fact, 
the Guide recommends this).

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

HTML doesn't really have the semantic range we need, IMO.

My copy of Mandrake had all the necessary packages installed; I just had 
to set up a few environment variables as it says in README.docs. Other 
distros may not be so lucky; but perhaps we should investigate why it's 
so hard on Windows, and try and provide documentation to make it easier?

Gerv