ISSUE-75: Specification Structure

Core - Jeni Tennison 3

Specification Structure

State:

CLOSED

Product:

LC Comment - RDFa Core 1.1

Raised by:

Manu Sporny

Opened on:

2011-01-13

Description:

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:

• ACTION-47 on Steven Pemberton to triage ISSUE-75. - due 2011-01-27, closed

Related emails:

1. ISSUE-81: Specification Structure, Part 3. (from Steven.Pemberton@cwi.nl on 2011-02-24)
2. ISSUE-80: Specification Structure, Part 2. (from Steven.Pemberton@cwi.nl on 2011-02-24)
3. ISSUE-79: Specification Structure, Part 1. (from Steven.Pemberton@cwi.nl on 2011-02-24)
4. ISSUE-75 (Core - Jeni Tennison 3): Specification Structure [LC Comment - RDFa Core 1.1] (from sysbot+tracker@w3.org on 2011-01-13)

Related notes:

Display change log