> > I think the documentation portion of the project could use people in roles > analogous to the core contributors with commit privileges and someone in a > role similar to the software release manager. > > Those with documentation commit privileges take on the responsibility of > proofreading documentation produced by others in the documentation team (or > making sure someone has proofread it for grammar, style, etc.), converting > it to DocBook format (if it's not already in that format), and committing it > to the repository.
Actually, this is how many projects work, so there you go. :-) > The goal of having a single person coordinating documentation work for a > given release would be to channel volunteers so that everyone's checking a > different piece of documentation to see if it is incomplete or requires > updates to match the current release of the software, and making those > changes. The one thing this scenario may softball a bit is that DocBook (or ANY decent documentation method) is complex enough that people really can't say, "Oh, I'll take this release -- I'll have DocBook down pat by the end of the week, thanks!" We'd really need some committed, skilled wranglers (even if the skills were acquired midstream). And ideally, we'd have a toolset that helped us with the wrangling. portion) per release, rather than the current hit-or-miss approach. The > release manager could also collect people's suggestions on what > documentation is missing ... Initially, we might consider a task force (not just a release manager) working very hard to identify all the missing documentation (or available but needs conversion/updating). Kind of a one-time-good-deal. > In this sort of context, the learning curve that DocBook poses is > completely irrelevant (assuming you have a large enough handful of core > commiters who know DocBook) Well... I'd have to disagree a wee bit here. I think this is where we'd have to be realistic about the size of the Evergreen community with respect to having a workforce for DocBook production. Even large communities have to scramble with documentation. One reason php.net built its toolkit (a non-trivial thing to do) was in response to this challenge. (See http://doc.php.net/php/dochowto/ ) And that's a much larger community where nearly everyone involved is fairly technical. Plus we'd want some web design help so the documentation wasn't painfully ugly. Even the toolset issue needs consideration. My experience with XML editors so far is they fall into the categories of free and bad, and spendy and good. To give you an example of the problem in this scenario with "cheap and bad," in the last few months, working with someone on a DocBook project, I sometimes found myself needing to review DocBook files that the free-bad editor wouldn't open, forcing me into the ultimate time-sink, eyeballing a lengthy XML file for missing angle brackets and such. This isn't to throw cold water on this post, but to (cautiously and with many caveats and warnings) suggest that Karen C. represents well here what has worked well for other projects and what might work well for Evergreen. -- -- | Karen G. Schneider | Community Librarian | Equinox Software Inc. "The Evergreen Experts" | Toll-free: 1.877.Open.ILS (1.877.673.6457) x712 | [email protected] | Web: http://www.esilibrary.com | Be a part of the Evergreen International Conference, May 20-22, 2009! | http://www.lyrasis.org/evergreen
_______________________________________________ OPEN-ILS-DOCUMENTATION mailing list [email protected] http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
