News from the Open Source Documentation Summit

[Dan Mueth <d-mueth uchicago edu>]

On Sunday July 16, O'Reilly sponsored the Open Source Documentation
Summit.  It was an informal meeting of about 20 representatives from the
open source documentation community, including a handful of O'Reilly
editors.  It included representatives of most of the main open
documentation projects (KDE, GNOME, LDP, FreeBSD, BSDi, O'Reilly), several
specialists on library sciences and software/content database
management(Metalab, Sourceforge, OpenContent), and a number of experienced
authors, editors, and hackers.  Many people fell into more than one of
these categories.  We discussed a variety of topics relating to
documentation, from tools to licensing to motivating writers.  I was
amazed to find that despite the seeming diversity of the attendees, most
people had the same concerns and problems.  It quickly became apparent
that we would all benefit substantially if we worked together more
closely.  For example, KDE has tools to help translators keep their
translated documents current with changing English documents, which many
projects could use.  This was generally true that each project had some
tool or expertise that everybody else wanted.  Everybody left energized
and enthusiastic, and with a short list of action items to work on in the
coming months.

I've tried to summarize some of the more important discussions and
decisions:

1) Everybody agreed that we should all try to standardize on the following
set: DocBook/XML, PNG, SVG, EPS, and Dublin Core/OMF(see below).

2) One of my biggest concerns coming into the Summit was how to manage
documentation on a system.  A good help browser should be able to: 1) Find
all the documentation on the system, 2) Sort the documentation into a
subject-based contents tree, 3) Know basic things about each document,
such as the language it is written in, its format, its title, and
hopefully things like the version, author, and a few other things, and 4)
Find documents which are stored on servers or the Internet. This clearly
cannot be done without knowing more information about documentation than
is currently stored on our systems.

This is actually a very old problem, solved by librarians long ago.  They
use metadata based on Dublin Core which describe many properties of each
book or document(ie. card catalogs).  The software maps at Sunsite and
Sourceforge are managed in a very similar way.  And, there are variations
on this used by book publishers to manage all their resources.  So, it is
only natural that we accept this standard to manage documentation on open
systems such as Linux and BSD.  The Metalab project had this idea a while
ago, and created the OMF which is a minimal subset of Dublin Core.  
(Minimal to keep the work load and expertise requirement on metadata
authors minimal.)  As a subset, it will still be fully compliant with the
Dublin Core standard.  This metadata will describe each document and point
to its location (local or on the internet).  There will also be a system
for storing and searching documents on the Net.

This was of particular interest to a number of projects represented and
was agreed upon by everybody.  We will be working over the coming months
to work on the details and develop the necessary tools.  Luckily there
were enough people present who were interested in working on this and with
varied expertise that this should go smoothly and quickly.  When it is
finished, we will have a system which will be shared by all the main
documentation groups.

[Any developers who are interested in helping with details on
implementation or hacking should email me at d-mueth@uchicago.edu.]

3) A number of groups have worked on tools which are of interest to other
groups.  The KDE team has tools to help translators keep track of
versions.  The LDP team has conversion scripts for moving documents to
DocBook.  I think there were others I am forgetting now.  We will be
gathering tools which are of common interest on a web site to be shared by
all the documentation groups.

4) Everybody thought we need a good XML authoring tool.  Only a couple of
us had heard of Conglomerate, so Eric Bischoff (KDE) popped it up on his
laptop and showed it to everybody.  It was received by lots of praise and
surprise.  Eric Raymond, who was sitting beside me, pointed out with
excitement that it even shows the type of markup in small type under the
text.  We have at least a couple people who are interested in hacking on
it.

5) It was recognized that many authors are motivated by recognition, and
so we decided that developers should be strongly encouraged to include
THANKS files in their packages which recognize documentation authors.


Generally, the Summit was highly successful.  We all left excited about
what we discussed and our plans.  Some people even suggested having
another meeting next year.

Finally, I'd like to thank everybody at O'Reilly who made this Summit
possible, productive, and enjoyable. They were all very nice to talk with
and did an excellent job organizing and facilitating the Summit.

Dan

PS: Frank Willison from O'Reilly also wrote a very nice article about the
Summit which includes a list of attendees.  It can be found
at: http://www.oreilly.com/frank/.