Re: ACTION-333 Quick Review of Quick Reference Guide

From: Bijan Parsia <bparsia@cs.manchester.ac.uk>
Subject: Re: ACTION-333 Quick Review of Quick Reference Guide
Date: Thu, 23 Apr 2009 09:40:05 +0100

> On 23 Apr 2009, at 09:03, Christine Golbreich wrote:
> 
>> A first quick comment about links.

[...]

> IMHO, NF&R serves yet a different purpose, rather, two different
> purposes: 1) it serves as a transition document, i.e., a Primer for OWL
> 1 people with a specific sort of focus on the new features; and 2) it
> serves as documentation of how to design useful extensions to OWL by
> documenting how we *did* design useful extensions to OWL. For 1, I
> expect, like the primer, those users to eventually outgrow it. For 2,
> they are coming to it in a totally different context. It's unlikely that
> they'd use or want to use QRG for that task.

Well said!  As well, if we decide to keep links to Primer, then Primer
is a much better document to serve as a gentle place for further
information about an OWL 2 feature.  If we decide to not keep links to
Primer then we are saying not to link to primer material at all, and the
links to NF&R go as well.

>> I suggest to keep all links to NF&R and Primer. Otherwise if you
>> consider that they are "not very useful", remove both links to NF&R
>> and Primer.
> 
> I would do this (i.e., remove both). It's not a matter of possible
> utility, but of appropriateness for the common use. The QRG is supposed
> to be a "quick" version of the *reference* material. The reference
> document is the Structural Syntax (by design). It provides a uniform
> description of the entire language with comprehensive examples. We
> *want* people to use it as their "go to" reference document (this is why
> we unified the old Reference and Syntax document).

> The better each document is fit for a clear, distinct purpose the more
> value it has, and, I think, the more value the document collection has
> as a whole. This is why I push back on scope creep and *apparent* scope
> creep. Apparent scope creep confuses readers and people trying to teach
> or train from the documents.

> Cheers,
> Bijan.

I would go along with removing the links to Primer.  They don't have
that much utility - users of QRG can always go to SS&FS.  However, I
would also go along with keeping the links to Primer.  They might help
people who might need a gentler discussion of some aspect of OWL 2 than
is provided by SS&FS.

peter

Received on Thursday, 23 April 2009 12:13:38 UTC