Re: Strawman RDFCore Documents structure

Brian McBride wrote:
> 
> I had an action from the face to face to propose a structure for the documents
> the WG is to produce.  Below is a strawman for discussion.

This is certainly useful for making me think about the structure
of this pile of work...
Hmm... somehow I got the impression that your structure
would include a schedule.

In particular, I'm interested to know which of these
documents is intended as an editorial revision/clarification
of the RDF 1.0 Recommendation, and which are new
work products (i.e. not already W3C Recommendations)
that need to go thru last call and
Proposed Recommendation...


> Brian
> 
> Objectives
> ==========
> 
>  o Provide precise, formal specifications of the RDF abstract model,
>    the RDF/XML syntax, RDF Schema and RDF vocabularies
> 
>  o Provide understandable, readable, approachable explanations to users
>    of RDF and RDF Schema.

Hm... I expected to see something like:

	o clarify the RDF 1.0 spec

in the top-level list of objectives.

> Target Audience
> ===============
> 
> The audience for these docuements can be broken down as follows:
> 
>  o Managers etc who want to know what RDF is about and whether they
>    should be using it.
> 
>  o Authors of technical books on XML, the semantic web etc.  The role
>    of developing tutorial material for the bulk of developers is filled
>    by the folks who write these books.
> 
>  o Higher layer semantic web standards designers who will build more
>    expressive capabilities on top of RDF.
> 
>  o Tool builders who design and implement tools that use RDF.
> 
>  o Data modellers who will design new data models using RDF.
> 
>  o application developers

I agree that's a desireable list of audiences to reach.
Whether it's feasible, I'm not so sure. I'd certainly
need to see a schedule before I could say whether I believe
it or not.

> Principles
> ==========
> 
>  o Strong separation of explanatory material from the hard core
>    specifications.  Only the hard core specifications are normative.
> 
>  o Use of formal techniques in the specifications where possible.

I'm all for formal techniques. Separating stuff isn't nearly
as important... especially if it results in lots of
readers having to swap back and forth between documents to grok.


> Documents
> =========
> 
> Overview
> --------

What you describe here is traditionally provided by
way of an Activity Statement. The activity statment
four our work is

  http://www.w3.org/2001/sw/Activity

but it's not a very good fit for what you're describing.
But it's not very consistent with other activity
statements, which are much more of the manager's overview:

[[[
Activity statements provide an executive overview of
     W3C's work in this area, while the XML Home Page
     points to highlights, events, specifications, discussion
     groups, software, and other resources.
]]]

--        Extensible Markup Language (XML) Activity Statement
http://www.w3.org/XML/Activity
Sat, 21 Apr 2001 07:52:10 GMT

It wouldn't be unprecedented for an exective overview to
be a separate document from the activity statement, though.
e.g.

  XML in 10 points 
  http://www.w3.org/XML/1999/XML-in-10-points

> 
> Purpose:  High level introduction to RDF and guide to other documents.
>           All that a manager needs to read to understand broadly what
>           RDF is trying to do without getting into how it does it.
>           Answers questions like "What is RDF?", "What would my
>           organisation use it for?", "Where does it fit into the
>           family of XML, metadata and semantic web specifications?",
>           "What do I read next?" and "What is defined and how can
>            it be extended?".
> 
> Audience: Everyone with any interest in RDF.  This is the  first document
>           a newbie reads.  It's the only document someone needing only
>           a high level view of what RDF is and what its for should need
>           to read.
> 
> Size:     2-3 printed pages
> 
> Status:   Non-normative
> 
> Style:    Short, concise, readable.
> 
> Tutorial
> --------
> 
> Purpose:  A tutorial introduction and explanation of the RDF specifications.
> 
> Audience: The primary target audience for this document is the book author.
>           The main goal of this document is to make the specifications
>           accessible to the book writing community, so that they can fill
>           in the gaps and write complete tutorials in their books.
> 
>           This document will also be used by those who eschew the books and
>           and want to figure stuff out for themselves from the
>           specifications.
> 
> Coverage: Sections covering all aspects of the RDF specs including the
>           abstract model, the RDF/XML syntax, RDF Schema and basic
>           vocabularies such as reification and containers.
> 
> size:     approx 20-30 printed pages
> 
> style:    explanatory
> 
> status:   non-normative


Looks good. The XML Schema Primer, while technically non-normative,
is always cited right next to the normative parts 1 and 2; and
it's the document I actually recommend that folks read in order
to learn XML Schemas.

> RDF Model
> ---------
> 
> purpose:  Formal specification of the RDF abstract model.
> 
> audience: Higher layer designers, tool builders, authors
> 
> coverage: Graph model, n-triple representation, model theory,

Why would n-triples go here?

Maybe it's necessary as an editorial device, much the way
BNF is used in the XML spec. but I wouldn't expect
it to be "normatively specified" as part of RDF.

Especially not if this "RDF Model" is intended as an
editorial clarification of the RDF 1.0 Recommendation.


>           n-triple formal grammar as non-normative appendix

Oops... I was reading too fast. I see you're already
headed in this direction.

> size:     < 10 printed pages
> 
> style:    Formal
> 
> status:   normative

Schedule: for release next week. ;-)


> RDF Schema
> ----------
> 
> purpose:  Formal specification of RDF Schema
> 
> audience: Higher layer designers, tool builders, authors
> 
> coverage: type, Class, etc and their model theory
>           Vocabularies - reification and containers and their model theory
>           XML Schema data types
>           links to test cases

Reification and containers go here? That's sorta sticky/tricky
w.r.t. endorsement/review process.

Hmm...

I wonder if we could look at this document as sort of a second
part of the tutorial.

i.e. RDF tutorial, Part I: for when somebody else designs the
	vocabulary(ies) and you're just filling in the instance data.

 RDF tutorial, Part II: making new vocabularies

> size:     < 20 pages
> 
> style:    formal spec, no explanatory material
> 
> status:   normative

Oops... you're not talking about tutorial stuff here.

Hmm...

> RDF/XML Syntax
> --------------
> 
> purpose:  Formal specification of the RDF/XML grammar and its
>           transformation to a graph.
> 
> audience: Higher layer designers, tool builders and authors
> 
> coverage: relationship to XML, grammar, transform to graph,
>           links to test cases

I'd be happy to see test cases integrated here as examples.

> size:     < 10 pages
> 
> style:    formal spec, no explanatory material
> 
> status:   normative
> 
> Test Cases
> ----------
> 
> purpose:  Machine executable illustrative test cases which illustrate
>           various aspects of the specifiations.  Not exhaustive.  Not
>           a validation test suite.  Explanatory examples.
> 
> audience: All except managers
> 
> coverage: everything
> 
> size:     ?
> 
> style:    machine executable with comments
> 
> status:   normative  (@@??)

I don't know whether it's worthwhile to make the test cases normative;
we don't have much precedent for that.

But I do want to see the test cases released as a whole; I expect
this will trigger implementors to check their work, starting
a feedback loop that results in more consistency/interoperability.

-- 
Dan Connolly, W3C http://www.w3.org/People/Connolly/

Received on Tuesday, 14 August 2001 13:53:45 UTC