[OPEN-ILS-DOCUMENTATION] Documentation Strategy Suggestion

[Karen Schneider]

>
> 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
| kgs at esilibrary.com
| Web: http://www.esilibrary.com
| Be a part of the Evergreen International Conference, May 20-22, 2009!
| http://www.lyrasis.org/evergreen
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://list.georgialibraries.org/pipermail/open-ils-documentation/attachments/20090506/b1dbde68/attachment.htm