[OPEN-ILS-DOCUMENTATION] Evergreen documentation issues

Thu May 14 18:53:12 EDT 2009

FWIW:

I know nothing about docbook. I could google I guess.
Drupal I know a little bit...

We now have some VRE's that are being used for "collaborative books".

These have automatic menu structure, full html formatting, revision
capabilities, rights and permissions by Role/Organic groups and diff
modules to compare revisions.

There are modules to present the data in a variety of formats. That os
bothe the beauty and the curse of clicky clicky Drupal... to know when
to stop adding modules!

The trick for getting folks to contribute documentation is that they
need to be comfortable with the tool being proposed, and not 
overwhelmed at yet another thing to learn.  

The tool, it's ease of use and "friendliness" will play a a big part
the quality, quantity and subjects of contributions. That being said
structure and control are important ...

My 2 cents...

F. Grant Johnson
  Systems Coordinator
  Robertson Library
  University of Prince Edward Island

>>> On Wed, May 6, 2009 at 12:55 PM, in message
<5efe72cf0905060855g2ed041b2md0653757c5a43064 at mail.gmail.com>, web
gurl
<georgiawebgurl at gmail.com> wrote: 
> Hi all,
> 
> I realize this is getting off-topic a little...
> 
> Interesting enough, I am about to start work on a separate
(non-Evergreen)
> project  to migrate a 220+ document manual to a new platform (from
html +
> pdf). At the moment, I am writing my scope statement (with input from
end
> users who are primarily librarians), so that  I will have a 'shopping
list'.
> I already have enduser buy-in, and the biggest needs are ease of use,
the
> ability for them to update their own documents, and the ability to
apply
> some control/security so that the documents are safe and archived
(only
> authorized users can make changes). Other items on the short list for
the
> 'shopping list' include support for various file formats, advanced
searching
> (I can always throw a Google CSE on  it, if needed),  multicategory
> organization. A wiki (Mediawiki/twiki/etc) will not work for this
group for
> a variety of reasons.
> 
> I am interested in Docbooks and I especially like the
crosswalkability of
> xml,  but I am exploring opensource document management software at
the
> moment. Drupal is on my list for consideration because I know that it
can
> handle the work that is needed. However, Drupal is a fairly robust
and can
> be complex CMS, so there may be other choices (although I do love
Drupal and
> it is certainly scaleable; love the book structure/toc for
documentation).
> In the past, I've also used KnowledgeBase to provide documentation to
web
> clients; DocMan  also looks to be good. My other consideration is
Dspace,
> which may be overkill, too, but certainly has alot of support.  I
would
> definitely be interested to see other (non-Wiki) documentation sites.
Please
> feel free to email me off list -- georgiawebgurl at gmail.com
> Thanks,
> Robin
> http://robinfay.net/site/
> 
> 
> 
> On Mon, May 4, 2009 at 4:20 PM, Lourie, Margaret <lourie at nelinet.net>
wrote:
> 
>>  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
>>
>> _______________________________________________
>> OPEN-ILS-DOCUMENTATION mailing list
>> OPEN-ILS-DOCUMENTATION at list.georgialibraries.org
>>
http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
>>
>>
> 