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 | [email protected] | Web: http://www.esilibrary.com | Be a part of the Evergreen International Conference, May 20-22, 2009! | http://www.lyrasis.org/evergreen
_______________________________________________ OPEN-ILS-DOCUMENTATION mailing list [email protected] http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
