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