I am not advocating Drupal but wondered if it might be suitable. I don't know of any Drupal uses for documentation but will ask around. I agree that it is important to be able to tie documentation to releases so you get the right information for your release, so that is one thing that makes the whole endeavor more complicated.
Interesting idea to have an easy input tool that then allows for conversion to a more functional system. Sounds like it might be a good way to go. I also agree that ease alone does not make people create content. There has to be a commitment to doing it, but the harder it is to do and the more time it takes the less likely that the content will get created. Maybe if we all come up with ideas for what we need the documentation to do that might point us towards the most useful tool. A few things that come to mind right away are web-based, be able to clearly relate/scope to a particular Evergreen version, and easy to input and easy to find what you are looking for. Is it possible to code documentation sections to a version so that you could scope your search to only the version that you want? I am not a documentation expert (as I have already revealed) but am glad to participate in finding our way to having good, useful 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 [email protected] ________________________________ From: [email protected] [mailto:[email protected]] On Behalf Of Karen Schneider Sent: Monday, May 04, 2009 4:09 PM To: Public Open-ILS documentation discussion Subject: Re: [OPEN-ILS-DOCUMENTATION] Evergreen documentation issues 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
