Documentation issues on the new website

[Jeff Waugh <jdub perkypants org>]

Hi all,

So, one of the features I've been working on for the new website build
system is to completely integrate documentation - both visually, and through
the build process.

Currently, that means putting docbook xml into the tree, and telling the
build system which xml file is the root (most large docbook documents are
split up and have a root file, this doesn't matter for single-file docs).

However, given that everyone likes building docs from CVS at the moment (see
API docs in the website, and the hideous methods used to make that work),
I've been looking at doing that.

It's coming to a point where I have to choose (note that I could do both
with a bit of extra hackery).

It would just require some metadata in the tree to say which module and path
the doc files come from in CVS, the appropriate tag or branch, and the root
file (makes it easy to provide different document versions simultaneously,
for 2.1 and 2.0, say). The build system would automagically check it out and
build it as if it were already part of the tree.

There are some reasons for and against this:

  - You can't validate the document before it needs to be built, so if
    anything's broken in CVS, it will also be broken on the site.

  - Less work for maintainers and documentors, because they don't have to
    think about the documentation beyond the metadata that the build system
    needs.

  - Documents change every day (could be good and bad), and they're not
    easily versioned (unless built from tags all the time).

I'm sure there are more.

What do the docs guys think? Would you prefer docs coming straight from CVS,
or the slight additional work of checking in working docbook sources into
CVS separately? Would you be interested in making sure every docbook checkin
to your modules worked, so that we could go purely with CVS on the website?

Thanks! :-)

- Jeff

-- 
                      Is Murphy's Law constitutional?