Re: User Facing Documents

On Oct 31, 2007, at 12:55 PM, Ivan Herman wrote:

> Hi Bijan,
[snip]
> Maybe it is worth to look at the first OWL 'suite' and see how the
> different documents scored in this sense. Unfortunately, I have only
> purely anecdotal evidence based on my own personal experience when I
> began to learn that stuff (and I had no description logic  
> background at
> all when I started [not that I would claim to have a solid one now
> either]), as well as when I talked to people at various meetings,
> tutorials, and the like. The two top scores were the OWL Guide and the
> OWL Language Reference.
[snip]

So, this is contrary to my experience and to my experience of people  
asking me questions (that picture is more complex because it include  
people who were confused or misled by the guide and reference;  
doesn't mean they are awful documents, but that they necessarily have  
limits; I'm the sort of guy people go to for that sort of stuff for a  
variety of reasons). This doesn't invalidate your experience, but it  
means we need something else to help adjudicate.

Furthermore, at the time, there was *far* less material available and  
far fewer tools. If you look at the Pellet lists, issues with OWA and  
CWA come up *far* more often than just about anything else.

My point is that what would be helpful, most helpful, or  
*worthwhilely* helpful isn't obvious or transparent. Companies like  
TopQuadrant weren't doing regular classes, to pick just one example.

So, which users are we trying to help? In what way? With maximal  
leverage of the *group's* time and energy? (Nothing stops *any* of us  
from producing user facing material in other venues. I do this every  
day by writing blog posts, working on class material, working on user  
documentation, answering email and irc questions....)

Nothing prevents the guide and reference being updated by people who  
like them! Nothing prevented this in the past year. But I wouldn't be  
surprised if the primary value in an update is that it brings people  
who already have invested a great deal in them along in an  
comfortable and straightforward way. That's hardly a negligible  
consideration! But it doesn't speak to the issue of how to *expand*  
the owl market and mindshare. I would bet that most barriers to  
adoption relate to missing language features and poor tool support  
(instead of W3C blessed user facing documentation), something which  
the working group is *uniquely positioned* to address, and thus  
should be our primary focus *as a group*.

For example, it's pretty clear that, if it isn't already, soon the  
most common user facing syntax will be the Manchester OWL API, via  
Protege4 and TopBraid Composer. (Note: I had nothing to do with its  
development and it's nowhere near my personally preferred syntax.)  
So, wouldn't it make more sense to have the guide and reference in  
terms of that? (at least, a variant?) What about in Turtle, which is  
comparatively rare in my judgement but much liked in certain circles?

(Inside the working group such choices can get us into trouble.  
Outside the working group, choice of primary syntax doesn't get you  
into trouble.)

(Of course, I am a tool vendor...so there is some bias there; but one  
reason I work on tools is the evident fact that most users prefer a  
lot of tool support and learn via doing.)

Just reminding that we don't actually have consensus on what the user  
facing documents the WG produces should look like, the timing of  
their publication, etc.

Cheers,
Bijan.

Received on Wednesday, 31 October 2007 13:41:06 UTC