Document number: P2138R1
Audience: EWG, LEWG

Ville Voutilainen
2020-04-14

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.

Revision history

Highlight the most recent changes:

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:

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:

The process

Once these issues were recognized and the alleviation for them agreed on, we established the following process for Design->Wording:

And, as mentioned earlier, the following process for Design<-Wording:

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:

"What's a 'wordsmith'? Who qualifies?"

A wordsmith is, by the definition for the purposes of this process, "a person who can write or help write CWG/LWG-consumable wording". It's ultimately the decision of the chairs of EWG/LEWG to decide what sort of wording they're willing to accept as wording incoming into their wording review (which might be less strict than the wording-group review), and those groups should have confidence that what they forward is written and championed by a person that won't be wasting Core's or Library's time.

CWG and LWG can also, if they so choose, arrange for a small group of their members to do this wording-work. Note, however, that such arranging must not consume group time, and is not the responsibility of the chair of the wording review group. Ask the members of EWG/LEWG to help you when the initial design review is done, ask a wordsmith that you know, ask on the reflector, but do not spend CWG's or LWG's time in the quest for a wordsmith.

Further explanation of the new process

So, to sum it up, let's bulletize the Design->Wording process:

  1. the design group, be it LEWG or EWG, decides after reviewing a proposal that it should go forward to LWG or CWG.
  2. 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.
  3. 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.
  4. 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.
  5. 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:

  1. 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).
  2. 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.
  3. the design group reviews the matter, and resolves it according to the Design->Wording process.
  4. the wording/technical review group continues progress on the proposal.

Or in a diagram: