Re: Documentation issues on the new website
- From: John Fleck <jfleck inkstain net>
- To: Jeff Waugh <jdub perkypants org>
- Cc: gnome-doc-list <gnome-doc-list gnome org>, gnome-web-list gnome org
- Subject: Re: Documentation issues on the new website
- Date: 13 Aug 2002 19:41:26 -0600
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
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]