[OPEN-ILS-DOCUMENTATION] Evergreen documentation issues

[Karen Schneider]

 Paul, this is terrific--and spot on. Before I respond I'm wondering if you
(and anyone else) can help assemble some "pre-work" for the docs discussion
at the conference? I.e. models to look at, things to consider.

Two small clarifications:

* The EG download page has had significant improvements -- even if it needs
more -- and the login for the dev server is on the page -- see
http://evergreen-ils.org/downloads.php

* Docs now has subversion control. Admittedly, it's existed for less than a
week, but it lives. ;)  But you are right, it's fundamentally empty. This is
part of the discussion for the conference.

Discussion:

Regarding the January 2009 proposal (
http://docs.google.com/Doc?id=ddzqk523_264f2vk5vpn ) ... One of the learning
curves I've had over the past six months doesn't exactly moot the January
proposal, but it does put it in perspective.

The learning curve has had a number of smaller curves.

One is that documentation won't write itself, particularly developer-level
documentation. The community is actually stepping up to do some fantastic
end-user documentation -- it could still use standardization (more of that
in the Docs discussion at the conference), but if you hunt around (and you
do need to hunt...) you'll find good stuff. I knew going in that
documentation won't write itself, but I really understand this more clearly,
and the proposal doesn't do justice to the question, how do we commit
resources to documentation development and maintenance. Dokuwiki... well...
it's almost as if we need a task force to blow it up and start over, but
that's a symptom of the higher-level problem (or lower-level if you're going
by Maslow's hierarchy).

Also, if we're going to commit to single-source documentation such as
DocBook -- and there are extremely good reasons for adopting this path, also
for discussion at the conf (though we can always go into it here) -- the
resources required are nontrivial. I've been following the DocBook project
for about five months, and worked closely with an intern, and I see now that
the proposal softballs what's involved. In fact, in the last couple of weeks
when I touched base with the DocBook community about the documentation
discussion at the conference, not one but several DocBook writers wrote to
ask me to please underscore the degree of commitment, investment, and effort
required to go this route. It's not that it isn't worth it, but we shoudl
commit to it with our eyes open.

There are other small things... such as that proposal recommends the Fedora
style guide as a model, but DocBook authors have recommended other guides
that are worth evaluating. But these are small details.

As you suggest, at least some of our "first needs" are a cross-project
functional workgroup on documentation -- not just people who might, at some
time, write some documentation, but people committed to solving the
overarching problem -- and a list of priorities, which you've really
started.

Thanks again! eg09, full steam ahead!

-- 
-- 
| 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/20090504/04bb6759/attachment-0001.htm