[OPEN-ILS-GENERAL] Documentation examples and a question
Karen G. Schneider
kgs at esilibrary.com
Sat Oct 18 09:58:21 EDT 2008
Duimovich, George wrote:
> A few quick comments on this:
> 1. I would eventually like to see "official documentation" being distinct from end user contributed documentation...
> 2. Longer term, we should be striving for sustainable and well structured models for supporting both "official documentation" and user contributed documentation. On the latter, there is a big positive with the recent Mellon/ESI project, and over time I hope & expect that we'll organize ourselves to fund sustained documentation efforts on both official and user contributed documentation as support contracts ramp up.
All of the points George raised are very well-taken.
1. With a relatively short completion timeframe, the documentation
project at THIS point is focusing on creating strong, effective content,
with the understanding that the documentation will be reframed in the
most appropriate containers. Note also that all of the "good"
documentation examples people talk about offer hybrid containers, e.g.
2. The idea of a canonical body of documentation is also
valuable--whether it is to ensure "what we translate," or whether it is
simply because as with development, there should always be a trunk. I
have separate thoughts about that as well. Surely we can provide a way
to showcase (and encourage) good field documentation while maintaining
the idea that there is always one body of documentation agreed upon as
3. Tapping the larger documentation-writing community is also a good
idea. Right now the Evergreen documentation project is beginning to
evolve from an ad hoc to a formal project, and there is also widespread
awareness that documentation must go hand-in-hand with development. In
an ideal world, there would be at least one true documentation writer to
lead that project. In the world we live in, we may get by with what is
4. As a note, the PostgreSQL ,Apache, and MySQL documentation projects
are particuarly good models to examine. Writing that, the question
bubbles up: perhaps there are people associated with these documentation
projects who can share their knowledge.
| Karen G. Schneider
| Community Librarian
| Equinox Software Inc. "The Evergreen Experts"
| Toll-free: 1.877.Open.ILS (1.877.673.6457) x712
| E-Mail/AIM: kgs at esilibrary.com
| Web: http://www.esilibrary.com
More information about the Open-ils-general