coordination between peer documents

In my "subject" I make this sound too technical.  Let me cite the
case in point that most recently reminded me of this.  This is
the question of how CAST's tool (Bobby) should refer to the Trace
guidelines.

The solution is that the document referred to [markup guidelines]
exports an interface or prototype analogous to a .h file, but
which contains at the minimum a set of URLs for the referring
[Bobby error messages] document to use in links.

This namespace has to be relatively stable.  The particular
discussion surrounding each topical entry point into the
Guidelines bookshelf can be updated without invalidating the
error message library in installed copies of the audit tool.  But
if you take away named anchors, or totally change the topic
associated with a name (likely to happen if you use ordinal names
such as sect_3_4 instead of mnemonic names) the interface
agreement has been violated.

The subset of the Guidelines information that it is important to
stabilize is the list of URLs (including #fragment's) and what
general topic is associated with each.  It is even possible to
add to the list.  Care must be exercised in taking away.

So long as you work jointly to stabilize the entry points, peer
documents can both be free to change without breaking the
cooperation between them.

I would actually like to expand the spec-for-spec a little and
suggest that we adopt an operating principle of requiring and
controlling document prototypes which contain

	- a table of contents
	- a narrative explanation of the document structure
	- an index of entry points

[Various of these can be combined if done carefully.]  The whole
thing to be an HTML [2.0] document, and the index of entry points
to contain a "model citation" for each entry point in the
document.  This scheme works for multi-file documents or
documents covering a range of topics where named anchors have
been used to provide topical specialization.

I am not saying that it is impossible to change the prototype for
your document after you have filed one.  But the prototype would
be regarded as a commitment to the community and would be placed
under tighter control earlier than the whole document.

I originally started to write this note to the Coordination Group
small circulation, but then I realized that the critical peer
relationships are between WAI documents and non-W3C documents.
We need a linking method that works across the boundary of what
we control.  And I expect that it is the Interest Group which
should make the call as to which external documents are on our
must-link list, and help us gain cooperation from the maintainers
of those documents.

If we can figure out a peer-linking practice that works for
cooperation with externally-maintained documents, then we can
simply conform to this practice with the drafts that we are
developing in concurrent tasks within the project.  The more
difficult requirement should drive how we do this, not the easier
one.

--
Al Gilman

Received on Tuesday, 9 September 1997 22:07:26 UTC