Document number: P2138R0
Audience: EWG, LEWG
Ville Voutilainen
2020-03-01
Rules of Design<=>Wording engagement
Abstract
This paper explains the rules of engagement that have been
in use between Evolution and Core, amends the rules with regards
to Evolutionary wording review, and proposes adopting the same rules
between Library Evolution and Library.
The amendment to the rules should change nothing for Core and Library
(well, not for worse, at least), it's merely a wording-runthrough
in EWG and LEWG before the material proceeds for technical/wording
review.
The <=> in the title is not a spaceship, it's two overlapping
arrows going into opposite directions.
Some historical background
The original problem
Way back when, not really important when, but a couple of years
ago, we had three problematic issues with material that flowed
from Evolution to Core:
- some material didn't have wording when it arrived on Core's
plate.
- some material had wording that hadn't been pre-reviewed by
a Core expert.
- some material needed to be sent back to Evolution, and
Evolution wasn't always prepared nor welcoming of such an
event of material being sent back.
The solution
To alleviate these problems, the Chair of Evolution specified
the following rules, although they weren't written down (a snag
that this document aims to rectify):
The rationale for these points shouldn't be hard to understand:
- Core is supposed to review a technical specification and make
sure it's worded suitably, accurately, and consistently, and
wording-wise and otherwise fits into the language. Doing so
requires having the actual wording that is proposed to be incorporated
into the Working Draft.
- Core doesn't write wording.
- Some members of Core might be so kind to help write wording.
- Core's workload is hefty, and the time of the experts in that
room is not used well if they are looking at a specification
that is nowhere near ready to have a chance to survive the first
5 minutes of review before there is a request to go away and
come back with proper wording. This is both about consistency
and completeness - the wording should be roughly similar to
the wording we already have terminology-wise, style-wise and
otherwise, and it must have all the things that are part of the
design.
- Core doesn't write wording.
- Some members of Core might be so kind to help write wording.
The process
Once these issues were recognized and the alleviation for them
agreed on, we established the following process for Design->Wording:
- Evolution reviews a proposal, and decides they are happy with
it and want to forward it to Core.
- The EWGChair queries/verifies the existence of the wording.
- In case it doesn't exist, the instructions for the paper
author are "find a wordsmith, produce wording, and report
back to me".
- In case it exists, the question is "has it been reviewed
by a reputable wordsmith? If not, have it so reviewed
and report back to me."
- Once EWGChair is satisfied with the reputable wordsmith's
report that the wording is ready for Core consumption, Core
is made aware of incoming material and the proposal author
is greenlighted to proceed to Core review at Core's scheduling
pleasure.
And, as mentioned earlier, the following process for Design<-Wording:
- Core reviews a proposal, and discovers a design issue.
- The CWGChair notifies EWGChair that something needs to come
back, and designates a Core champion to explain the issue in Evolution.
- EWGChair schedules such a discussion with elevated priority,
and we iterate again, with the Design<->Wording rules as before.
The New Rules
Rather than the chair of a design group making sure that wording
exists and is ready for the technical/wording review group's consumption,
that responsibility now lies with the whole design group. That is,
once the proposal author has made sure their wording is either written
by a wordsmith or reviewed by one, they approach the design group
(with the wordsmith) and give a presentation about the wording, illustrating
how it implements the design, and report whether any oddities or questions
surfaced.
If such oddities or questions did surface, the design group needs
to discuss them and possibly clarify their design.
This rule change is made for a couple of reasons:
- the design groups must understand the technical consequences
of their designs
- the design groups must double-check that the design is accurately
implemented by the wording, instead of saying very late in the process
that "that's not what we meant" or "that's against the design intent".
So, to sum it up, let's bulletize the Design->Wording process:
- the design group, be it LEWG or EWG, decides after reviewing
a proposal that it should go forward to LWG or CWG.
- if the proposal has wording, the design group must run through
it and verify that the design is wholly and accurately implemented
by the wording, and that there are neither omissions nor additions
that the design doesn't cover.
- if the proposal does not have wording, the design group must
not greenlight the proposal to go forward; they must instead
instruct the proposal to come back with the wording.
- when the proposal has new wording not yet reviewed in the second
bullet, go back to the second bullet.
Repeat as many times as necessary.
- once the run-through is complete, and the design group is confident
that the wording implements the design wholly and accurately, the
design group sends the material onwards, forwards.
Let's also bulletize the Design<-Wording process:
- the wording/technical review group reviews a proposal and discovers
a design-level addition/omission/bug/issue/snag, or a technical
problem (an implementability problem, a consistency problem, or
some other problem).
- the chair of the wording/technical review group makes sure
the problem is minuted, sends a heads-up to the chair of the design
group, and designates a champion that can explain the problem to
the design group.
- the design group reviews the matter, and resolves it according
to the Design->Wording process.
- the wording/technical review group continues progress on the proposal.
Or in a diagram: