[OPEN-ILS-DOCUMENTATION] Evergreen documentation issues

Mon May 4 16:20:20 EDT 2009

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

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 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
| 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/56a5ee81/attachment.htm 