Hello!
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 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.
d. Committer adds new document outline to document scratchpad area in cocoon cvs. Once in cvs, announcement sent to cocoon-dev, e.g. "[REVIEW] this-document-name".
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 [EMAIL PROTECTED] (still waiting for [EMAIL PROTECTED] to start functioning...)
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
