[OPEN-ILS-GENERAL] Documentation examples and a question

[Karen G. Schneider]

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. 
http://www.postgresql.org/docs/manuals/

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 
"the" documentation.

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 
possible.

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