ed: organization: conformance and terminology

I just read the spec
	http://www.w3.org/TR/xlink/
	http://www.w3.org/TR/2000/WD-xlink-20000221
front-to-back, and I have some editorial editorial suggestions...
nothing in this message proposes any change to what is specified.
I'm copying spec-prod because I think this stuff relevant to
the way we produce specs in general.

Move section 4. "Processing and Conformance" before section 3.
As it is, while reading thru the spec, until I got to section 4,
I didn't know the focal point of the spec, and I wasn't really
sure which end was up.

Also, move the may/must RFC2119 para under the conformance heading,
and move 1.3 Terminology under there too. This will make the
separation between the "fluffy" stuff in section 1 and 2 and the
more formal stuff that's now in sections 3 and 4 more clear.

By way of example, take a look at the HTML 4 spec is organized:

	1.1 How the specification is organized
	http://www.w3.org/TR/1999/REC-html401-19991224/about.html

and

	4 Conformance: requirements and recommendations
	http://www.w3.org/TR/1999/REC-html401-19991224/conform.html


Oh... by the way... have you done a review to be sure that
you are actually using the may/must/should terminology consistently?
I suggest you do that, and mark up such occurences
ala <strong class="rfc2119">may</strong> in the generated HTML...
maybe use CSS smallcaps in the stylesheet.
Currently, there are several occurences of "can" that seem
like they are intended in the RFC2119 sense of "may"; e.g.
in 2.3 Attribute Value defaulting: "attribute defaults
(fixed or not) can be added to a DTD..." .

Note that once you move the conformance section earlier and
subordinate the terminology section under there, you can
eliminate redundancy between
	[Definition: ] application
		...
and
	An application is XLink-conforming if ...

Similarly for [Defintion: ] link and linking element (what's the
difference between those, by the way?) vs. "An XML
element is XLink-conforming if ...".

In general, I find these definitions out of context unhelpful.
(I did it that way for HTML 2.0, and in retrospect, I'm
quite confident that it sucks as an organizational technique.)

Continuing down that list, I suggest moving [Defintion: ] arc into the
context
of section 3.1.3 "Traversal rules ...". If you want to collect
the terms and definitions into a glossary, very well, but make that
glossary refer to the definitions in context, rather than trying
to make it stand on its own. I prefer such a glossary to go
at the end, ala an index, but putting it up front is OK as long
as the forward references are clear.

Most of the other defintions (ending resource, inline link,
multidirectional
link, out of line link, ...) seem like they would fit better in
section 3.1 "Extended links"... somewhere in section 3, at least.
I think the prose in 3.1 actually does define
these terms again, but the connection between that prose in 3.1 and the
definitions in 1.3 isn't clear... there are no links/cross-references
in either direction, for example.

The spec appears to define the term URI-reference (and resource?), but
in fact, it is just importing them from RFC2396. I think the
use of the [Defintion: ] notation for importing terms is very
misleading.
Also, the relationship between the term "sub-resource" in this
spec and the term "fragment identifier" in RFC2396 should be made
explicit and clear.

More on citing other specs separately...

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

Received on Thursday, 9 March 2000 13:14:08 UTC