Re: ACTION-333 Quick Review of Quick Reference Guide

On 23 Apr 2009, at 09:03, Christine Golbreich wrote:

> A first quick comment about links.
>
> - NF&R says what a new feature is and not only why a new feature has
> been added. If it turns out that NF&R has unvoluntary been too much
> cut and gives a wrong impression, it's urgent to say it. I will revert
> and reintroduce some content of previous version.
[snip]

I think Peter just meant the NF&R has a different purpose than a  
reference. As does the Primer. Neither are intended to sure as  
reference documents for the language. If we tried to make them do  
that, we would compromise their fitness to their *own* purposes.

For example, if we make the Primer "work" as a reference, we  
discourage people from using the proper reference document and  
necessarily crowd out some teaching material. In the *best* version of  
the Primer (imho), a newbie starts by reading and relying on it a lot,  
but over time, stops using it for the language description parts (and  
starts relying on the Syntax spec, perhaps via the QRG). In other  
words, the Primer is a bit like training wheels.

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.

> 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.

Received on Thursday, 23 April 2009 08:40:41 UTC