Re: Strawman RDFCore Documents structure

I think this represents a reasonable starting point for structuring the
material, provided we don't take the descriptions too literally.  That
is, I think we can use this as defining rough targets for the different
types of material we need to produce, and in the case of the Overview a
rough length target, so we can think about actually writing.  However, I
don't know that I'd want to spend a whole lot of time discussing much
greater detail about the documents, because I often find that when I
actually start to see the material my ideas about how much is needed,
and how to organize it, change.  

A couple of additional comments:  

1.  I suspect many of the page estimates are too low.  

2.  I'm suspicious of *too much* separation of explanatory material
("Tutorial") from the specification of the RDF model and RDF Schema. 
This is one place where I'd want to actually be looking at some
material, in order to decide whether the specification was actually
going to get across to people or not.  While I appreciate the desire to
avoid mixing normative and non-normative material (as well as the desire
to avoid confusing people with too many detailed examples), nevertheless
we need to shoot for specifications that our target audience can
actually read and understand.  (For example, a potential "explanatory"
section of the specifications that might be very useful, based on the
history of our WG discussions, would be a section whose title was
something like "virtual specifications: things you may be reading into
the specifications, but that aren't actually there.")  Also, I wouldn't
think that having a "tutorial" would necessarily rule out having
explanatory material in the specifications themselves;  I generally
think of a "tutorial" as having a different approach than a
"specification", even when the "specification" contains a lot of
explanatory material. Perhaps a thorough cross-referencing scheme
between the two "kinds" of documents would alleviate many of the
potential difficulties.  
  
--Frank

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.
> 
snip
> 
> Documents
> =========
> 
> Overview
> --------
> 
> 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
> 
> 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,
>           n-triple formal grammar as non-normative appendix
> 
> size:     < 10 printed pages
> 
> style:    Formal
> 
> status:   normative
> 
> 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
> 
> size:     < 20 pages
> 
> style:    formal spec, no explanatory material
> 
> status:   normative
> 
> 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
> 
> 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  (@@??)

-- 
Frank Manola                   The MITRE Corporation
202 Burlington Road, MS A345   Bedford, MA 01730-1420
mailto:fmanola@mitre.org       voice: 781-271-8147   FAX: 781-271-8752

Received on Tuesday, 14 August 2001 13:00:43 UTC