ISSUE-75: Specification Structure

Core - Jeni Tennison 3

Specification Structure

LC Comment - RDFa Core 1.1
Raised by:
Manu Sporny
Opened on:
From Jeni Tennison:

My final general point is an editorial one: the spec contains the same (or similar) information in multiple places, and this can make it hard to work out where to look for given information and may mean that there are inconsistencies which are hard to identify.

There are three specific cases where this is particularly bad.

First, information about CURIEs is available in:

* Section 3.8 Compact URIs (under 'RDF Terminology')
* Section 6 CURIE Syntax Definition
* Section 7.4 CURIE and URI Processing

It would be good to integrate these, or at least the second two, into a single section.

Second, information about the content of the different attributes is available in:

* Section 5 Attributes and Syntax
* Section 7.4.4 Use of CURIEs in Specific Attributes
* Section 8 RDFa Processing in Detail

as well as being implicitly scattered in Section 7.5 Sequence. I would like to see the normative definitions of the types of values accepted by the attributes in only one place (probably Section 5).

Finally, information about how to process RDFa documents is defined in both:

* Section 7.5 Sequence
* Sectio 8 RDFa Processing in Detail

When I was implementing RDFa 1.0, I found this particularly problematic. I ended up trusting Section 7.5 (or whatever it was then) and ignoring Section 8. What I would like to see is one of these sections becoming non-normative, so that there is a single authoritative place within the spec that defines how to process RDFa.

FWIW, I generally prefer a declarative definition to a procedural one, but Section 8 is written more as a sequence of examples than a detailed definition of RDFa processing, so of the two I think that it should be the one made non-normative.
Related Actions Items:
Related emails:
  1. ISSUE-81: Specification Structure, Part 3. (from on 2011-02-24)
  2. ISSUE-80: Specification Structure, Part 2. (from on 2011-02-24)
  3. ISSUE-79: Specification Structure, Part 1. (from on 2011-02-24)
  4. ISSUE-75 (Core - Jeni Tennison 3): Specification Structure [LC Comment - RDFa Core 1.1] (from on 2011-01-13)

Related notes:

Issue split up into Issues 79, 80, 81

Steven Pemberton, 21 Jan 2011, 14:36:42

Display change log ATOM feed

Chair, Staff Contact
Tracker: documentation, (configuration for this group), originally developed by Dean Jackson, is developed and maintained by the Systems Team <>.
$Id: 75.html,v 1.1 2015/03/27 14:12:31 vivien Exp $