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 case. Hope this helps, Cliff -------------------------------------------------------------- Cliff Woolley [EMAIL PROTECTED] Charlottesville, VA --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
