[OPEN-ILS-GENERAL] Documentation examples and a question

[Duimovich, George]

A few quick comments on this:

1. I would eventually like to see "official documentation" being distinct from end user contributed documentation; understanding of course that subject matter experts from the user community could undoubtably be part of creating any formalized documentation. A good example bandied about comes from the pg community:
   example: PostgreSQL official docs - http://www.postgresql.org/docs/ 
   example: PostgreSQL community documentation - http://wiki.postgresql.org/wiki/Main_Page

To support the need for this distinction through one example, consider internalization efforts. In order to provide documentation in multiple languages consistently, we need to be able to identify an authoritative body of work to translate. It's a lot easier if we can say, "translate these documents" and have some consitency and authoritativeness with non-English implementations.  

2. Longer term, we should be striving for sustainable and well structured models for supporting both "official documentation" and user contributed documentation.  On the latter, there is a big positive with the recent Mellon/ESI project, and over time I hope & expect that we'll organize ourselves to fund sustained documentation efforts on both official and user contributed documentation as support contracts ramp up.

3. We should try to shore up the docuwiki and any efforts towards other "packaged" documentation with insights from the professional technical writing communities. Further, on standards, we have both DITA and DocBook that could be explored, especially in regards to any production of the "official" stuff. Both standards are designed to support XML-based architecture for creating and delivering technical information, but IMHO, DITA appears to be more appealing..

DITA vs. DocBook:
	http://blogs.sun.com/coolstuff/entry/modular_docs_part_1_why
	http://blogs.sun.com/coolstuff/entry/modular_docs_part_2_dita

4. The Process. Futhering on points in 3 above, check out an example set of processes identifying 8 phases here:
     http://www.dclab.com/dita_global_local.asp

It's just an example, but I think it outlines a couple of points of interest (e.g. Master Topic List + workflow identification, etc.). Obviously, we'll have to find out what works for everbody and available resources, but part of the way we can ensure our documentation grows well is to continue to evaluate and then embed some decent processes in the game early enough.

Karen, I'll contact you offline about a few other ideas.

George Duimovich
NRCan Library / Bibliothèque RNCan

-------------------------------------------------------------------------------

Some of you may know that there is a documentation project afoot, funded
through a Mellon grant to Georgia Public Library Service specifically for
this purpose. We have contractors working on this project as we speak.

However, we are also aware that some libraries have developed some very good
documentation -- a bit here, a bit there. You can see some examples from
Indiana Evergreen and SITKA here in this related Evergreen
delicious.combookmark set:
http://delicious.com/EvergreenILS/documentation

There are many different ways to present this information, but one approach
might be to link it here in the logical place within the documentation
hierarchy (with the authors' permission, of course!):

http://evergreen-ils.org/dokuwiki/doku.php?id=evergreen-user:evergreen_end-user_documentation

The librarian in me wants to add the format, date or version, and of course,
the author, and link to and provide access to each version.

The documentation worked on for the grant may incorporate bits from the best
documentation in the wild -- again with the authors' permission -- and
attempt to claim space as "the" documentation, so there is at least one
canonical version actively maintained.

Thoughts?