Re: Documentation issues on the new website

[John Fleck <jfleck inkstain net>]

On Tue, 2002-08-13 at 19:18, Jeff Waugh wrote:
> 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.
> 

Coolness.

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

So I'm sure I'm understanding here - what you're talking about using
this method is essentially a second copy of the doc (beyond the original
in cvs) that lives somewhere in webland?

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

I expect this to be a minor problem. I rarely run into docs in cvs that
don't validate.

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

If you can make the hackery work, I think we would be better off with a
system that automagically pulls the docs from cvs. My anecdotal
experience (based on past efforts to keep the doctable updated) is that
a second task beyond checking a doc in will often be forgotten.

Cheers,
John
-- 
John Fleck
jfleck inkstain net (h) jfleck abqjournal com (w)
http://www.inkstain.net http://www.abqjournal.com

"Sometimes, a diner is all about the mac and cheese." 
  - Zippy the Pinhead