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?
