[UFDTF] My action to compare documents - a starting point for discussion tomorrow

Hi,

First, I mentioned to Alan that I've been looking into the form and 
structure of user documentation from a technical writing perspective, 
and I've also attempted to compare our documents with others produced in 
the W3C for other standards.  I've also tried to be thoughtful about 
what our Sandpiper users would be looking for in these documents. 

Secondly, for those of you who don't know, we (Sandpiper Software) 
currently sell an add-in to IBM Rational Rose for ontology development, 
which imports and exports OWL (1.0), converts "vanilla" UML class 
diagrams, etc.  We are also close to releasing a beta version of our 
second generation tool on No Magic's MagicDraw and Eclipse, which is 
ODM-compliant from a graphical notation standpoint, and are porting this 
to IBM's RSA and Sparx EA tools.  I haven't been very vocal about our 
work to avoid any indication that we're using this forum for marketing 
purposes, but think it's important for folks to understand that we are 
building and selling tools that use these specifications.  Our users are 
primarily early adopters and researchers in aerospace, agriculture, 
financial services, manufacturing, and government sectors.  They are 
-not- typically AI or KR researchers, but they tend to be folks who have 
stumbled across RDF and OWL because they were desperate for a solution 
to some really hard problems, and at the same time they needed a 
UML-based approach because of internal corporate standards requirements, 
the need to interoperate with other model repositories, and/or 
requirements levied on them by their research sponsors.

With that in mind, I've provided a few thoughts that came up as I was 
reviewing the documents as a basis for the discussion tomorrow morning.  
Note that I can only stay on for the first 35 to 40 minutes of the call, 
as my nanny is no longer working mornings for us and I need to get Tommy 
up and ready for school.


1.  General Observations

It appears from looking at other W3C technologies that there is little 
consistency in the set of documents various working groups choose to 
provide from a user-facing perspective.

The rec trak RDF documents include only a primer.  RDFa docs include a 
primer, SKOS includes a guide.  On searching the W3C site, one gets 
similar numbers of hits for primers and guides, but twice as many as the 
two combined for overviews.


2. Overview

A number of the Overview documents I browsed appear to be a short, sweet 
description of the purpose of the specification, high-level description 
of the application landscape (use cases for OWL, but not very 
technical), in some cases but not all, a "how to read the rest of the 
documents in this collection/set", and in some cases but not all, a 
synopsis of the features of the specification.

The original overview included a document roadmap, which provided a very 
high-level (too high-level IMHO) summary of the document landscape, a 
short paragraph on"why owl" and the technical gaps it fills (still 
useful), and a terse description of the language, including what is in 
OWL Lite vs. DL and Full.

A number of our customers use this document as a basis for getting 
started.  It's short, easier to navigate than some of the other docs, 
and fills their end-user need to remind themselves quickly about some 
language feature.

For our end-users, something like this, or something that serves as the 
"tri-fold commercial quick start cheat sheet" is really useful.  I don't 
think that either the primer or guide fill this need; it should be 
complementary.  We can recreate it for our users, of course, but if they 
need it, why wouldn't other users?

I would like to see a new overview (possibly renamed Overview & Quick 
Start) that
    (1) provides a short description of the purpose of the language, as 
in paragraph 1 under *Potential New Overview* in Deb's email of 
2007-12-07, and includes a better document roadmap, since they can get 
what was in the prior version simply by looking at the OWL page
    (2) a new section that provides the high-level description of the 
application landscape for the user community
    (3) incorporates the content of the OWL 1.1 overview indicating 
what's new in this version, but does not send users away by using the 
technical DL expressivity language
    (4) a feature summary that provides the "quick start" guide, perhaps 
taking the lead from the structure that was in the original overview and 
the outline that Deb and Evan developed (same email - see 
http://lists.w3.org/Archives/Public/public-owl-wg/2007Dec/0098.html), 
but that is very terse and links to appropriate places in the 
specifications for additional detail.

The audience for this should be end-users of the language, not 
necessarily tool builders or DL experts.  I think such a document would 
add significant value for our (Sandpiper) users at a minimum, and could 
provide a friendly, light-weight introduction that the other documents 
necessarily lack.


3. Guide or Primer

A user guide, or primer, typically provides an introduction and 
high-level tutorial, with examples providing instructional guidance on 
the best ways of doing things.  A decent document coming out of this 
group should be fairly substantial in my view, with a number of 
examples, references to decent papers, references to some of the work 
that was done in best practices, or perhaps updating some of that 
material to incorporate new features of the language, etc.  I don't care 
which name we use for it, although primer implies tutorial for me more 
than user guide does.  This document has a very different purpose from a 
reference manual or functional/structural specification -- it should be 
instructional - providing users with insight into how one might use the 
language to develop OWL-based applications.

Having said this, I like features of both the original guide and new 
primer, and have issues with both. I think we could easily reuse some of 
the better features of each, for example expanding on the orientation 
section of the new primer to cover more potential user communities, but 
we should make sure we cover most, if not all, of the language features 
(I'm not sure the primer does this, but haven't read it carefully to 
look for that), include the cross reference, glossary, etc. of the 
original, along with a number of references that people can go to for 
more information, and, more in line with the draft SKOS guide, graphics 
-please-.  There are none in either the old guide or new primer, which 
needs to be fixed. I do like the "show me the source code in my favorite 
notation" features that Bijan uses in the new document - very nice.

I like the idea of using and extending the same example(s) all the way 
through, and I like the fact that the original guide described an 
example application that people could play with at the end.  I think 
this is appropriate for such a document, whether or not we retain the 
wine example, since some folks like it alot and others find it 
culturally problematic.  Chocolate, cheese, or perhaps olive oil might 
be nice alternatives, since they are similar in complexity and 
structure, and all three have artisan variations we can classify and say 
various things about (I was in a shop last week that sells olive oil and 
very little else - see http://www.oliviersandco.com/ if you're 
curious).  We should definitely include some of the family relationships 
that are in the new primer, since they are easy to understand and 
provide a view on some of the richness we are adding with the new 
language features.  This shouldn't be difficult even if we choose 
something like olive oil or cheese, since some families have been making 
them for generations.

Again, the audience for this should be end-users not necessarily tool 
builders, though some instructional material on description logics, 
especially in talking about the new features of the language, or on 
methodology for developing ontologies that leverage certain features for 
reasoning purposes is appropriate.  This should not be redundant with 
what we would include in the core specifications in my view.

Also, I think attempting to discuss ontology management, ontology 
alignment and mapping, and ontology versioning (covered thinly in one or 
the other) are out of scope, aside from, at most, providing links to 
research or emerging example systems, such as Karlsruhe's OMV and 
Stanford's BioPortal for the management piece, in these areas.

If there is general consensus in the UFD TF that this is what we want in 
a guide/primer, I'm willing to spend more time thinking about an outline 
and digging deeper into what we have already as starting points.

Thanks,

Elisa