httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Cliff Woolley <>
Subject Re: Tips for nascent doc effort
Date Sat, 04 May 2002 19:12:19 GMT

Just thought I'd give you a developer's perspective on this one to add to
what Joshua said.

On Fri, 3 May 2002, Diana Shannon wrote:

> initiatives, past and present, lately. Sadly, many of them die. A number
> of people within the Cocoon community are worried about moving
> doc-related discussions off cocoon-dev prematurely, fearing developers
> will disconnect from the documentation gestation process altogether. Was
> this a concern for you? How did you manage the transition?

As Joshua said, the primary responsibility lies with the developers,
particularly in API documentation (which we keep in the header files
themselves in Doxygen/Scandoc format to make it hard to forget to update
them).  It would be nice if developers would document new configuration
directives they add or ones they modify, that's SUPPOSED to be a
requirement.  We often forget.  Fortunately this kind of change doesn't
happen very often.  That's one way in which the docs project can help us
out... they keep a much-needed watchful eye on us.  :)

> How do you keep developers or SMEs (subject matter experts) involved in
> the documentation effort?

I guess I already answered part of this.  The flip side is that I know
there are many developers (including myself) who, while we don't actively
go about improving the documentation, do "listen in" on this list.
Inter-group communication seems to be the key.  The docs people (or at
least Joshua) listen to what we're doing, and we listen to what the docs
project is doing.

> Our proposed process includes the following steps: a. Author consults
> topic status list (a web page on cocoon web site) to make sure no other
> draft on this topic is in process. Author sends patch via bugzilla to
> topic-status.xml to "claim" the topic. b. Author reads the appropriate
> how-to author a <document-type-name /> document c. Following guidelines
> and templates, author submits proposed document outline via Bugzilla.
> [snip]
> What do you think about this process

Wow, that's quite a lengthy process.  I'm in the "think it's too formal,
has too many hoops" camp, I think.  All too often, both in the docs
project and in the code itself, it's not uncommon, unfortunately, to have
worked on something and to *beg* for someone else to review your work, and
nobody does.  There's just too much work to go around to have that much of
an editorial process.  Volunteer open-source projects don't work quite the
same way as professional publishing companies do in that regard.  I agree
with Joshua that you will probably find that so much red tape gets in the
way of frequent contributors who just want to get things done.  If the
code itself had that much review, yes it would be better, but it would
also never GO anywhere.

I will say that the straight-up CVS approach has worked incredibly well
for this docs project.  Commit-then-review is just as appropriate for a
docs project as it is for the code itself IMO, and this project stands as
proof of concept.

My only big thought is that you seem to imply that once a document is
written, reviewed, and released, then that can just be "it" if you do it
carefully.  I'd counter that that doesn't work when documenting a moving
target.  By necessity, just as much if not more work must be done to keep
the existing documentation up to date with the code as is done in adding
new documentation.  While the process you describe would work great if the
documentation could be "write once," I think you'll find that's not the

Hope this helps,

   Cliff Woolley
   Charlottesville, VA

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message