[OPEN-ILS-DOCUMENTATION] ACQ and Reporting documentation

[George Duimovich]

Regarding your questions:

1) Local needs that can't be met by community or vendor resources lead to
"local documentation." Then local documentation can be too customized for
local needs so that it makes it difficult to re-contribute it to the
community (I spoke with one OSS user recently who thought they had great
documentation to contribute to a project, but thought it was "too
customized" and therefore was reluctant to contribute because of the work,
etc. to de-customize it).

Further, when you need it, we'll take any documentation we can find in any
format, and local contributions can be invaluable. But some effort needs to
be made to standardize and give a common look & feel to user certain
contributions so that support resources don't get too confusing.

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. The Postgresql project has a good reputation for
documentation and they've got two good sites that demonstrate different
production vehicles:
Created using DocBook: http://www.postgresql.org/docs/manuals/
Using Wiki: http://wiki.postgresql.org/wiki/Main_Page

Their wiki provides a good example and includes some alternate languages
(another eventual consideration for documentation site).

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, so that the community could eventually
rely upon additional formalized, technical writing resources to compliment
community volunteer efforts. The needs will only get greater as migrations
continue, but so too will the capacity to respond as libraries eventually
wind down their existing contracts and make new ones with ESI and other lead
vendors, etc. The GPLS development is very positive.

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.


On Mon, Aug 11, 2008 at 9:49 AM, Karen G. Schneider <kgs at esilibrary.com>wrote:

> Some of this has been discussed on the PINES lists, but this is broader
> than PINES. This is a proposed change in tactic for documentation intended
> to work better for everyone.
>
> Initially the idea (as I understand it from former list traffic and
> discussion with some key folk) was that people in the field would be trained
> and documentation would flow organically from the field. In practice, though
> there are some excellent documents out there (and more about those in a
> minute), the training never was fully realized, and the would-be
> documentation writers were often too tasked with their primary work duties
> (and as a working librarian, I can fully relate--particularly in this crazy
> budget climate) that documentation didn't flow organically anywhere.
>
> In retrospect, this isn't surprising and it's also not anyone's "fault."
> The original volunteers were troopers to raise their hands, and it was a
> great idea that simply ran up against real-world realities.
>
> Meanwhile, GPLS/PINES have grant funding specific to writing documentation
> for Evergreen reporting and acquisitions -- which is a wonderful thing that
> will benefit the entire Evergreen community. We at Equinox are reviewing
> writing samples, searching for contract workers, etc. This work needs to
> happen before January. If you have names to consider, please email me at
> kgs at esilibrary.com.
>
> We all know the best documentation when it doesn't happen in a vacuum and
> has a lot of real-world input. So in thinking about what the documentation
> community could do, I came up with these ideas. How does this sound? What do
> you think? What would you add?
>
>  1. Some libraries have developed excellent local documentation. This
>     will be very helpful material for documentation writers to work
>     with. Sharing these would be valuable. Do we want to include local
>     examples directly on the documentation wiki?
>  2. To paraphrase Justice Potter, many of you on this list know good
>     documentation when you see it. Your feedback and input are
>     exceptionally valuable. You can be the "many eyes" for open source
>     documentation. Your thoughts?
>  3. Keeping the documentation in wiki format ensures that if you see
>     an area for improvement, and you have wiki access, you can make it
>     happen. Or you can share here on the list and someone with access
>     can make it happen. Would this work?
>  4. Much key development for Evergreen has happened because libraries
>     funded it or contributed labor toward it. My own initial thought
>     is that in the future, documentation should be part of
>     development--funded, contributed, however--and should roll out
>     hand-in-hand or at least closely after the actual software
>     releases. What do you think?
>
> --
> | 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
>
> _______________________________________________
> OPEN-ILS-DOCUMENTATION mailing list
> OPEN-ILS-DOCUMENTATION at list.georgialibraries.org
> http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://list.georgialibraries.org/pipermail/open-ils-documentation/attachments/20080811/07c5ab76/attachment.html