[OPEN-ILS-DOCUMENTATION] Evergreen documentation issues

Mon May 4 15:44:14 EDT 2009

I second thanks to Paul for bringing up the need for migration
documentation. I hope we will be able to agree on a platform that is
easy to use and can be set up relatively quickly so we can get started
on writing (and using) the actual documentation. 

I am concerned about the DocBook approach because if there is a steep
learning curve then the documentation won't get written. It has to be
easy so people will do it and create useful documentation. I hesitate to
suggest yet another platform to look at, but at NELINET we moved our
website to Drupal and have had very good results. It is now so easy for
us (staff and our members) to contribute content that we (staff) are all
actually doing it. I can't speak for how much work and time it takes for
the setup, but once it was set up we are all able to contribute and edit
content very easily.

Has anyone else been using Drupal? If so, what do you think about this
as a potential platform for documentation?

Margaret

-----------------------------------------------------------

Margaret Lourie
Consultant, Technical Services
NELINET, Inc.
153 Cordaville Road
Southborough, MA 01772
Direct phone line: 508-597-1942
Phone: 800-635-4638, ext. 1942

Direct Fax: 508-597-1992

Fax: 508-460-9455

lourie at nelinet.net

________________________________

From: open-ils-documentation-bounces at list.georgialibraries.org
[mailto:open-ils-documentation-bounces at list.georgialibraries.org] On
Behalf Of Karen Schneider
Sent: Monday, May 04, 2009 3:28 PM
To: Public Open-ILS documentation discussion
Subject: Re: [OPEN-ILS-DOCUMENTATION] Evergreen documentation issues

 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/3298e63b/attachment.htm 