[OPEN-ILS-DOCUMENTATION] Evergreen documentation issues

[Karen Schneider]

>
> I am concerned about the DocBook approach because if there is a steep
> learning curve then the documentation won’t get written.
>

This is a concern, and definitely, format should be on the table. But...

1. Other documentation projects have developed workflows -- and tools -- for
producing documentation that allow single-source documentation expertise to
be concentrated in a handful of folks. One example is php.net, which has
taken DocBook and modified it (with php, of course :) ) to create a workflow
that fits their needs.

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

2. It's entirely possible that the origins of documentation may begin in
other formats (as the proposal itself states).  There is even a Drupal tool
for generating Docbook XML ( http://drupal.org/project/export_docbook ). The
question is when we're talking about canonical, community-approved, tagged,
release-bound, no-fooling documentation, what format should it be in?

Note that for years we've had an "easy" tool -- DokuWiki -- but that hasn't
lead to the consistent production of documentation. (It can be argued that
it has worked against it -- because documentation schemata tend to "guide"
documentation into structure; DocBook has a clear
book/chapter/article/section/para hierarchy that encourages clear markup and
organization.)

Now, if the project had a style guide, a task force, a Czar or Czarina, that
might happen on any platform. But the question is what do we want? The
January proposal suggested some goals. How well would Drupal help the
project reach its goals?

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

3. Having used Drupal in a library setting, my take is that it certainly has
its uses. But can you point us to documentation projects that rely on
Drupal?  Also, how well does Drupal lend itself to the capabilities of
single-source documentation (of which DocBook is just one of several
formats), such as translation, upgrade paths, tagging to releases, etc.?


-- 
-- 
| 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/95df5c82/attachment-0001.htm