[OPEN-ILS-DOCUMENTATION] Evergreen documentation issues

Wed May 6 11:55:09 EDT 2009

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

-- 
http://contentdivergent.blogspot.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://list.georgialibraries.org/pipermail/open-ils-documentation/attachments/20090506/183096d1/attachment-0001.htm 