Review of Primer Doc

I have annotated the primer document on the wiki with smaller comments 
and updates.

I am including here higher level issues for discussion.

OWL Primer Review

Review last updated March 23, 2008

Review version - http://www.w3.org/2007/OWL/wiki/Primer

Overall comments:

The document has valuable content and will be useful to some set of 
potential OWL 1.1 users. I expect it to be even more useful after the 
planned sections are completed – in particular after the longer example 
(proposed for the current section 7) is finished. This document is being 
proposed as a document that will meet the deliverable of a user guide so 
one thing considered in this review is if the 1.1 primer is as 
accessible as the OWL 1.0 Guide was and if it is targeted for the same 
or different audience. As I write this, I realize we never concluded the 
discussion Alan had started on the “Who reads our documents page” and 
which descriptions of users we wanted to target with individual 
documents. Perhaps we may want to reconsider that suggestion.

Organization:

There have been a few comments and suggestions about some portions of 
the document that may go in an appendix. I suggest that we aim the 
document to be readable in one pass by the most prototypical target user 
and put in the appendix material that may be found by the more trained 
or more ambitious reader. For example, I believe it is a valuable 
contribution to have a number of orientations for reading the document. 
There are a number of them though and some are more aimed at people such 
as knowledgeable database people. We may also want to have more of these 
perspectives as the document evolves. I suggest two things for orientation:

1 – in the main part of the document include the different orientations 
and have a one or two sentence description of the point.

2 – in an orientation appendix, include more details – at about the 
level that is in the current document aimed at each of the different 
orientations.

3 - I also suggest getting a reader for each of the orientations who 
self classifies themselves as part of that community. For example, lets 
find a database person to read the db section and see if that addresses 
their concerns. I think one perspective on these sections could be to 
give a short sales pitch for why someone from each of the individual 
communities would come to OWL. For example, with databases, one reason I 
find database people consider owl is the convenience by which they can 
make schema updates. I think the current database segment may not sell 
OWL to database people since it mentions that users (who treat owl 
information as complete… are often surprised or confused. We might want 
to reword that to

1 – suggest why a database user wants to use OWL

2 – remind them that users of complete systems will notice a difference 
(and mention the positive and negative aspect of the difference.

Syntax:

We have heard requests for additional syntax presentations. We have also 
heard comments about which ones to include. I think the technical option 
of hiding and showing different syntax options with one button click is 
great.

I think one thing we must decide is how to start the guide. I suggest 
the default being to show one syntax and hide the rest. My user 
community would find the document easiest to use if it used the same 
syntax as the previous documents – thus the default for those users 
would be the RDF/XML format.

I propose that we gather input on

(1) which syntax to use as the default

(2) which syntaxes to include

(3) if we should make an effort to limit the number of different syntax 
options.

We also may want to point out which syntax options are new over the OWL 
1.0 documents so as to minimize confusion.

Connection to the Recommendation Documents.

Given that this is a 1.1 version of OWL, I believe we need to at least 
acknowledge the OWL 1.0 documents so that users can learn history if 
they desire and can also access the past docs. Many of the examples will 
still be useful. I suggested adding them into the end of the section 
where to go next where a number of links were provided. I think it is 
most important to link to the 1.0 guide since this document is proposed 
as its 1.1 replacement.

Scope:

I think we need to provide the longer example (and this I believe is in 
the plans for the section currently numbered 7. I think we should 
consider OWL tools out of scope for this document.

Jie Bao made a number of good points in his review - 
http://www.w3.org/2007/OWL/wiki/Talk:Primer

with respect to background material and accessibility. I will not repeat 
them in this review but will mention that I agree with his points.

Received on Monday, 24 March 2008 00:41:32 UTC