httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <>
Subject Tips for nascent doc effort
Date Fri, 03 May 2002 14:28:03 GMT

I've been perusing your archives, trying to glean some advice as to how 
this group's experience might aid a new effort to improve documentation 
for Apache's Cocoon project. I'd be grateful for *any* tips, on- or 
off-list, that you may have about the following:

1. I assume Apache documentation-related discussions began on a list 
like apache-httpd-dev. If so, when did it move to a separate docs lists? 
How many people, particularly developers, subscribed/participated 
initially? I've been looking into a number of open source documentation 
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? How do you 
keep developers or SMEs (subject matter experts) involved in the 
documentation effort?

2. I'm hoping to address a number of problems with insufficient docs by 
encouraging community contributions of faqs, howtos, tutorials, case 
studies, etc. I'm working on how-to guidelines for all of these types, 
schemas, and templates. Our proposed process includes the following 
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 /> 
c. Following guidelines and templates, author submits proposed document 
outline via Bugzilla.
d. Committer adds new document outline to document scratchpad area in 
cocoon cvs. Once in cvs, announcement sent to cocoon-dev, e.g. "[REVIEW] 
e. SMEs, editors, and all interested parties make comments
f. Author writes document draft, based on revised outline.
g. Author submits draft as patch via Bugzilla. Committers update 
document in scratchpad.
h. Once in the CVS all interested persons address holes and other issues.
i. QA testing begins. Revisions performed as necessary.
j. After a vote, document moves out of scratchpad and into
the distribution proper.
k. Community/author submits patches as appropriate via
the normal Bugzilla process.

What do you think about this process? Some think it's too formal, has 
too many hoops. They think authors will be discouraged by it and not 
contribute. I'm not sure the pure cvs model works for documentation as 
it does for code. For example, when code has holes, it breaks or 
performs unacceptably. People have a great incentive to fix it. When 
documentation has holes, potential users and evaluators give up. There's 
a much weaker incentive structure for fixing documentation. I'm hoping 
such a process will minimize these problems during initial development 
and not rely so much on maintenance. What do you think?

3. Are there any disadvantages in having a separate cvs branch for docs?

4. I downloaded your cvs, but it isn't clear how you manage the document 
life cycle (draft -> iterations -> release). Is this managed through 
strictly through cvs versioning or included as some form of meta data 
within the docs themselves?

Any other tips, hard-earned advice very welcome. And please let me know 
if anything we are doing might prove useful to your efforts.

Thanks for reading!

Diana Shannon
(still waiting for to start functioning...)

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

View raw message