Specification editing process notes
Status of this document
These are notes about processes that I have used for working on
specifications within a working group. They are not endorsed by anybody
anywhere, and may be incomplete or wrong.
Please send comments on this document to the spec-production mailing list (Archives are publicly
available).
Last played with $Date: 2001/05/16 15:38:20 $ by Charles McCN
A process for working on specifications
This really comes from working on WAI specifications, which generally come
with a short, normative specification called Guidelines, which include a set
of requirements that are called checkpoints and an informative document that
is an appendix - called Techniques.
Rationale:
- Not making changes that the group hasn't seen clearly called out helps
people to keep rough track of what is there.
- Publishing frequently with small changes that have been explicitly
agreed is helpful.
- Checkpoints are the most important part of what we say. Guidelines are
organising principles, although some guidelines might also be
checkpoints.
- Techniques are in fact anything that is useful but non-essential
information, or things that will not be useful in all cases
Process requirements
- No edits are made to checkpoint or guideline text including checkpoint
rationale unless there is an explicit resolution of the group (as called
by the chair).
- For proposed changes to the text, an email should be sent detailing the
actual new wording proposed. This includes the editor.
- For changes to subtext (not the sort of note that expands a checkpoint,
but the paragraphs of explanation after a guideline...), the editor or
proposer should send them to the list. In the first instance, the editor
says whether or not they are being adopted - if someone objects then it
becomes a matter for formal proposal and consensus
- For examples and techniques, anything proposed as a new item is
included. Changes should be dealt with like changes to subtext.
- Issues can be noted in the document. A seperate issue list should also
be maintained noting when an issue is raised, and when and how it is
resolved. (W3C are in process of installing Bugzilla to use for
this...)
- Proposals should be sent to the working group with a single thread (i.e.
a single email) for each proposal.
- A change list should also be maintained. Again, it is useful if the
changes can be reflected in the document, at least to the last draft.
CVSWeb sort of does this, but it isn't X/HTML aware. There is also a diff tool that
Norm Walsh made to do it