[OPEN-ILS-DOCUMENTATION] ACQ and Reporting documentation

[Karen G. Schneider]

3) Wiki format -- I like the medium, and it's a great vehicle for 
end-user contributions - it's all good. But I'm unsure of is how well 
our needs could be met from user contibutions vs. any "official" 
professional tech writer created documentation.

-----------

To clarify, I don't mean user-generated documentation should replace 
"official" documentation--although we may want expert users to be able 
to contribute to the project (perhaps not as formally as the coding 
"commit" process works, but with some oversight). I'm talking about 
publication platform -- that is, using the wikis as the home base for 
documentation editing -- which is actually true for most (but not all) 
of the existing documentation anyway. I say this in part because behind 
scenes I've been industriously crafting suggested revisions to older 
material and some new material (FAQs and whatnot), and as far as 
end-user material goes, the stuff that's not locked up in static web 
pages is much easier to modify -- and for that matter, read. I have a 
hunch not many people print out the 1,913-page PostgreSQL manual... but 
I bet quite a few people search its webbier (and no less formal) 
counterpart.
> 4) The challenge right now is the intense "ramp up" phase that this 
> market sector is going through. I'm sure this is already in the plan, 
> but ESI and other future EG vendors, need to ensure that their support 
> and maintenance fees incorporate documentation costs ...
An excellent point. Documentation can't be an afterthought. As a writer, 
I gently observe that many people think anyone can write -- that they 
have the time, and the ability, and that it's easy. Time is always in 
short supply, and as for writing itself, sportswriter Red Smith put it 
best: "There's nothing to writing. All you do is sit down at a 
typewriter and open a vein."
> I would just add that we need to focus some efforts on manageable 
> areas in the context of different documentation types ("User Guides"  
> versus "Developer Documentation"). I'm not involved enough yet to know 
> where, but on the surface it would seem to me that there's got to be 
> some "quick wins" in the face of the huge challenge of documenting a 
> fast moving, dynamic development project.
That's where the grant funding for documentation is such a -- I almost 
wrote blessing, I hope no one's offended by that. The "quick win" 
identified at first blush is end-user documentation for reporting, 
followed by acquisitions (with really good end-user documentation often 
stealing into the arena of technical documentation). This was specified 
in the grant award from Mellon.

But grant funding has one weakness, which is that it lacks a 
sustainability mechanism. Your point about making documentation an 
integral part of the development effort (initial and ongoing) is key.

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