Subject: Re: [rfc-i] business process re-engineering

From: Julian Reschke <[email-masked]>
Date: Tue, 1 Mar 2022 11:00:03 +0100

Am 01.03.2022 um 03:49 schrieb Christian Huitema:
> ... > Maybe it is an issue of when, not how. Imagine that there was an "editor
> review" during last call, much like the other directorate review. The
> editor review could flag all the places where the text is problematic,
> maybe propose alternatives. It would then be the duty of the authors to
> fix that before the RFC progresses, and thy could do it using their own
> tools.
>
> There would still be a final pass, going from draft format to RFC
> format. But that would arguably be much simpler, and AUTH48 could be
> just that.
> ...

+1000
_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 1 Mar 2022 11:02:38 +0100

On 1. Mar 2022, at 00:24, Benjamin Kaduk <[email-masked]> wrote:
> 
> On Tue, Mar 01, 2022 at 12:17:24AM +0100, Carsten Bormann wrote:
>>> A full review should not be necessary. 
>> 
>> I wish that were true...
> 
> IMO a full review is necessary, not least to ensure that the document
> remains self-consistent and that any changes applied during editing are
> uniformly applied to all relevant parts of the document, not just in the
> subset of places that the editor noticed.

Absolutely.

(One more example for an API change, but not within the document: 
The most recent AUTH48 document I’m involved with has 69 <tt tags.  
The RFC editor rightly noted:

>> FYI, the text rendering of the <tt> element was changed in Sept. 2021 
>> (xml2rfc release 3.10.0). <tt> no longer yields quotation marks in the 
>> text rendering. 
>> 
>> It does yield fixed-width font in the HTML and PDF outputs. 
>> In light of this, please review and let us know if you want to 
>> make any changes (e.g., add quotation marks that would be in all 
>> three output formats).

The documents were of course mainly authored before the semantic change.
So one more task for the full reread: 
Check that the sentences still are understandable in the TXT form with the <tt information lost, and decide where quote marks need to be added.
This can only be decided by metamorphosing into a newly interested reader and reading through the text.
As noted in Star Trek 6, those metamorphoses can be exhausting.)

Grüße, Carsten

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 1 Mar 2022 11:04:37 +0100

>> format. But that would arguably be much simpler, and AUTH48 could be

Directorate reviews now increasingly come with a pull request on the side.
I hope that would be true for this kind of review as well.

Grüße, Carsten

---

From: Jean Mahoney <[email-masked]>
Date: Tue, 1 Mar 2022 10:04:11 -0600

(Putting on my RPC Project Manager hat)

Hi all,

Thank you for the spirited discussion! The RFC Production Center is 
evaluating its tool chain and processes, and I wanted to let you know 
that I'm listening to your feedback on these threads.

Best regards,

Jean Mahoney
RPC Project Manager

On 2/28/22 4:42 PM, Carsten Bormann wrote:
> On 28. Feb 2022, at 23:23, Peter Saint-Andre <[email-masked]> wrote:
>>> But categorically denying any progress can be made in this space strikes me as suboptimal.)
>> We have a classic tussle on our hands.
> I don’t think that is a tussle.
> After all, the RFC editor function is interested in doing a good job.
> So let’s give them the input they need.
>
>> We'll need to figure out a balance between the interests of authors (recognizing that different authors work different ways) and the interests of the editors, while keeping an eye on the costs (not only financial but also time to publication and so on).
> Well, the RFC editor function has to figure that out.
> Like so many areas of work where the simple answers produce suboptimal results.
>
> We get there not by making grand five-year plans, but by running experiments like the one the authors of RFC9180 seem to have run.
> (I’m looking forward to some data from the authors and the RPC on how well that worked and what made it work.)
>
>> Oh, let's also recognize authors who use a cutting-edge or "best practice" authoring workflow today (continuous integration etc.) will have moved on to something even more cutting edge five or ten years from now.
> Now that smacks of the old “we’ll get even better later so we don’t need to get better now” argument.
> (But I agree we don’t want to push the RPC into our fads (*).)
>
> Grüße, Carsten
>
> (*) In 2006, I would have pushed for the authors and the RPC to collaborate via subversion.  In 2022, I’m felling quite well pushing for using git (and possibly GitHub).  That doesn’t mean the the 2006 push would have been wrong in any way.  Neither subversion nor git have been/are fads.  (And they replaced CVS, which I seem to remember I used to collaborate on my first few RFCs except the one we inexplicably did in Microsoft Word.)
>

---

From: Michael Richardson <[email-masked]>
Date: Tue, 01 Mar 2022 14:11:56 -0500

Christian Huitema <[email-masked]> wrote:
    > Maybe it is an issue of when, not how. Imagine that there was an "editor
    > review" during last call, much like the other directorate review. The editor
    > review could flag all the places where the text is problematic, maybe propose
    > alternatives. It would then be the duty of the authors to fix that before the
    > RFC progresses, and thy could do it using their own tools.

This is something I'd also like to see.
Note that we are basically already doing this with the less formal, Sunday
afternoon editing/tutoring sessions that started before the pandemic.

    > There would still be a final pass, going from draft format to RFC format. But
    > that would arguably be much simpler, and AUTH48 could be just that.

exactly.
If the language is fixed before all the other reviews finish, then we can be
sure that we are arguing about the same things.

--
Michael Richardson <[email-masked]>   . o O ( IPv6 IøT consulting )
           Sandelman Software Works Inc, Ottawa and Worldwide

---

From: Jay Daley <[email-masked]>
Date: Wed, 2 Mar 2022 14:10:46 +1300

> On 1/03/2022, at 10:15 AM, Mark Nottingham <[email-masked]> wrote:
> 
> 
> 
>> On 1 Mar 2022, at 5:08 am, Joel M. Halpern <[email-masked]> wrote:
>> 
>> It seems to me it is untenable to expect the RPC to work with the soruce form of all the authors.
>> And the community has nothing resembling agreement on what the source form should be.
> 
> Thankfully, I don't think that's necessary. Things can improve significantly when the RPC avoids spurious changes to the XML in their process.
> 
> For example, up until relatively recently, they hand-linewrapped the XML they produce, introducing a lot of noise in diffs. After this was pointed out, they stopped, with the result that it's easier to recreate the XML from whatever format the authors used and compare it to what the RPC has done.
> 
> Some of the adjustments have to come on the tool side for other formats; e.g., I've been opening issues against Carsten's tool when it's not capable of producing the XML that the RPC uses.
> 
> Aside from that, guidance about how to use the XML is sorely needed; the vocabulary we've designed is sprawling and its application is not always obvious. For example, the RPC seems to always want to use <dl> to document a registry entry, but AFAICT that isn't documented anywhere, and so many authors will use other constructs (like <ul>) that need to be converted by the RPC.

Do you have any current examples of where spurious changes to the XML are introduced?  (In saying that, I count changes such as the <dl> one you mention above not as spurious but not well enough explained).

Jay

> 
> Cheers,
> 
> 
> --
> Mark Nottingham   https://www.mnot.net/
> 

-- 
Jay Daley
IETF Executive Director
[email-masked]

---

From: Mark Nottingham <[email-masked]>
Date: Wed, 2 Mar 2022 12:28:28 +1100

Hey Jay,

Currently (I have 7 drafts in AUTH48), the biggest ambiguity I'm encountering is when to use a dl vs ol vs table vs ? for things like registry entries.

For example, in this (not-yet-in-AUTH48) draft:

... I've just converted many things to tables, but it's not clear to me whether the RPC will change them to DLs or something in AUTH48.
  https://httpwg.org/http-extensions/draft-ietf-httpbis-retrofit.html

The problem is that when the author chooses the wrong starting point, RPC edits will make very large diffs in those areas, which makes it harder to pick up more semantic changes.

Also, as Carsten mentioned, default attributes are added to some elements in a way that's not easily reproducible. Right now I'm using a script to try to minimise that.

I will say that things are *much* better than they were even six months ago -- thanks to both Carsten and the RPC for their work, attentiveness, and flexibility here.

Cheers,

> On 2 Mar 2022, at 12:10 pm, Jay Daley <[email-masked]> wrote:
> 
> 
>

---

From: Jay Daley <[email-masked]>
Date: Wed, 2 Mar 2022 15:03:26 +1300

> On 2/03/2022, at 2:28 PM, Mark Nottingham <[email-masked]> wrote:
> 
> Hey Jay,
> 
>  https://httpwg.org/http-extensions/draft-ietf-httpbis-retrofit.html <https://httpwg.org/http-extensions/draft-ietf-httpbis-retrofit.html>

I see.  Your previous suggestion of a <registry> element or similar seems eminently sensible.  We do indeed have an odd hybrid of semantic and layout markup in RFCXML.

For info, <dl> will soon be in the RFCXML templates: https://github.com/ietf-authors/rfcxml-templates-and-schemas/issues/6

> The problem is that when the author chooses the wrong starting point, RPC edits will make very large diffs in those areas, which makes it harder to pick up more semantic changes.

That makes sense, thanks.

> I will say that things are *much* better than they were even six months ago -- thanks to both Carsten and the RPC for their work, attentiveness, and flexibility here.

thanks
Jay

> Mark Nottingham   https://www.mnot.net/ <https://www.mnot.net/>
> 
> [email-masked] <mailto:[email-masked]>
> https://www.rfc-editor.org/mailman/listinfo/rfc-interest <https://www.rfc-editor.org/mailman/listinfo/rfc-interest>
-- 
Jay Daley
IETF Executive Director
[email-masked]

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 2 Mar 2022 08:55:20 +0100

> I see.  Your previous suggestion of a <registry> element or similar seems eminently sensible.  We do indeed have an odd hybrid of semantic and layout markup in RFCXML.

We will be able to do this once IANA makes up their mind about the generic structure of a registry entry.

(One function that only works in a haphazard way right now is direct links to the HTML representation of registries or even registry entries; this might also benefit from some formal modeling of what’s in IANA registries.  In the end, we want to make sure we can reference IANA registries from formal languages such as YANG, CDDL, and ABNF without ad-hoc plumbing for each registry.)

> For info, <dl> will soon be in the RFCXML templates: https://github.com/ietf-authors/rfcxml-templates-and-schemas/issues/6

It already is in the markdown template that is buried at the end of:

https://authors.ietf.org/en/templates-and-schemas

(BTW, I find it weird that https://author-tools.ietf.org does not offer a prominent link to https://authors.ietf.org)

Grüße, Carsten

---

From: Jean Mahoney <[email-masked]>
Date: Wed, 2 Mar 2022 10:12:56 -0600

Hi Mark,

>    https://httpwg.org/http-extensions/draft-ietf-httpbis-retrofit.html

[JM] (Putting on my editor hat and skimming quickly) I don't believe I'd 
change any of the tables in this doc.

A table may be converted into a definition list because the contents are 
too wide (too many columns) and/or there is difficulty in controlling 
line breaks. We prefer not to use XML elements or entities to control 
the line breaks (e.g., <br/> or &nbsp;) in case the document is ever 
re-rendered. If they can be used sparingly, then the table format can be 
kept.  If there is just one row in the table, perhaps a definition list 
would be a better fit. For example, this too-wide table with only one 
row would be converted to a definition list:

                                                    Well-Known
URI Scheme   Template   Description   Status       URI Support    Reference   Notes
--------------------------------------------------------------------------------------
baz 	     prov/baz   baz           Provisional 	- 	  [RFC9999]   Only on
                                                                               Tuesdays
--------------------------------------------------------------------------------------

A table like the following would be turned into a definition list 
because, well, it's a table of definitions:

    Term          Definition
   ---------------------------------------------------
    Foo           A Foo is is type of a Combobulator...
    Bar           Bars are Transmogrifiers that ....

We also convert unordered lists to definition lists when they have the 
following format (terms and descriptions separated by colons or hyphens):

    * Combobulator:  Assembles packets mysteriously.
  
    * Transmogrifier:  Transforms packets into any desired item.

Best regards,

Jean

>> On 2 Mar 2022, at 12:10 pm, Jay Daley<[email-masked]>  wrote:
>>
>>
>>
>>> On 1/03/2022, at 10:15 AM, Mark Nottingham<[email-masked]>  wrote:
>>>
>>>
>>>
>>>> On 1 Mar 2022, at 5:08 am, Joel M. Halpern<[email-masked]>  wrote:
>>>>
>>> Mark Nottinghamhttps://www.mnot.net/
>>>
> Mark Nottinghamhttps://www.mnot.net/
>

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 2 Mar 2022 18:04:15 +0100

On 2022-03-02, at 17:12, Jean Mahoney <[email-masked]> wrote:
> 
>  For example, this too-wide table with only one row would be converted to a definition list:

If you can tell me some rules on how this should be done, I can put in code in kramdown-rfc that does this automatically (based on setting a flag, of course).

(This will need to distinguish between the two-column table, which gets a single definition list and a multi-column one, which gets a sequence of definition lists, because for the latter the table heads need to be repeated as the definition terms.)

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Wed, 2 Mar 2022 18:42:10 +0100

> (This will need to distinguish between the two-column table, which gets a single definition list and a multi-column one, which gets a sequence of definition lists, because for the latter the table…

This is an interesting discussion, but it seems to me we're trying to
solve a non-issue here.

IANA instructions are just that: instructions to IANA. They need to be
written in a way that makes it clear what actions are requested. If,
during IESG review, IANA is ok with the document, that should be the end
of the story. There's absolutely no need to spend time on reformatting
the instructions WHEN THEY ALREADY HAVE BEEN EXECUTED.

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 2 Mar 2022 18:45:44 +0100

> the instructions WHEN THEY ALREADY HAVE BEEN EXECUTED.

Much of the work on a document happens before they have been executed, and IANA considerations are often a very important part of that work.
So it is useful to have a smooth way to transition the result of that work into its RFC form.

(Unfortunately, there are currently also restrictions in what part of the IANA Considerations actually can be moved over to the registry, making it even more important to keep them useful as an after-registration reference.  We could of course also work on this construction site…)

Grüße, Carsten

---

From: Jean Mahoney <[email-masked]>
Date: Wed, 2 Mar 2022 14:21:08 -0600

Hi Carsten,

> If you can tell me some rules on how this should be done, I can put in code in kramdown-rfc that does this automatically (based on setting a flag, of course).

[JM]  A basic indication that a table's formatting is problematic is a 
warning from xml2rfc when outputting text. For instance: "Warning: Total 
table width (71) exceeds available width (69)". Note that the HTML 
output may not have any issues, but we still need to fix the formatting 
so that the text output is in good shape.

Does kramdown-rfc have a similar warning that would let an author know 
that they should take a look at how a particular table is constructed 
and perhaps adjust it?

As for adding new flags to kramdown-rfc, the RPC is working on providing 
more guidance to authors on using XML elements. When that is solidified, 
perhaps kramdown-rfc could be updated with new validation features.

Best regards,

Jean

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 3 Mar 2022 09:14:36 +1100

> On 3 Mar 2022, at 3:12 am, Jean Mahoney <[email-masked]> wrote:
> 
> [JM] (Putting on my editor hat and skimming quickly) I don't believe I'd change any of the tables in this doc. 

Thanks!

---

From: Martin J. Dürst <[email-masked]>
Date: Thu, 3 Mar 2022 09:01:40 +0900

Hello everybody,

Like Julian, I'm also somewhat skeptical. There are clearly cases where 
tables work much better for some kind of information, including registry 
information. One reason is that it can be much more compact, another is 
that much information will end up in table form at IANA anyway.

Regards,   Martin.

On 2022-03-03 02:42, Julian Reschke wrote:
>> If you can tell me some rules on how this should be done, I can put in 
>> code in kramdown-rfc that does this automatically (based on setting a 
>> flag, of course).
>>
>> (This will need to distinguish between the two-column table, which 
>> gets a single definition list and a multi-column one, which gets a 
>> sequence of definition lists, because for the latter the table heads 
>> need to be repeated as the definition terms.)
>>
>> Grüße, Carsten
>

---

From: Julian Reschke <[email-masked]>
Date: Thu, 3 Mar 2022 08:23:09 +0100

> so that the text output is in good shape.

Let me disagree here.

Do not tune the input to address shortcomings in plain text output (or
PDF output).

Best regards, Julian

---

From: David Noveck <[email-masked]>
Date: Thu, 3 Mar 2022 07:08:58 -0500

On Mon, Feb 28, 2022, 6:24 PM Benjamin Kaduk <[email-masked]> wrote:

> IMO a full review is necessary,

My opinion is different.  If I followed your approach, a lot of documents
would have been delayed and probably abandoned.  I've been involved as
author/editor for a number of multi-hundred-page documents.  The results
were not perfect but the documents were improvements over the documents
they replaced and that is enough for me.

not least to ensure that the document
> subset of places that the editor noticed.

The changes made/proposed at editing are made by someone that is not an
author, is not part of the working group and should be rejected if they
raise potential difficulties such as you are worried about.

I cannot see how a large set of co-ordinated changes such as you are
worried about can be made by someone who is not an author.

    -  if a split infinitive is corrected, then the correction can be
approved without a further search for similar instances.  Each case is a
separate judgement call.
   - similarly with corrections of commas.
   - if a large set of co-ordinated changes is proposed, whose nature would
require a full rerevew, they should be rejected, as politely as possible.
If that is not possible for some reason, the working group should have the
opportunity to weigh in, but that option should be very rarely used.

> This is analogous to a situation that arises when doing code review.
> If you change an API's semantics,

"If it hurts when you do that, don't do that".

You should not be changing an APIs' semantics as part of a code review.
Those
Semantics should be agreed to before coding starts.

you had better go around and check
> all the callers of that API to see if they need adjustments, not just the
> callers of the API that your test suite happens to exercise.

Sound like a nightmare to me, since such adstments might require further
adjustments.

With
> specifications we do not have the rigid rules of function names to identify
> the places to check, and the safe thing to do is read the whole document
> with any changes that were made fresh in mind.
>

The safe thing is to limit changes after consensus to those that do not
require such extensive review by the authors who may, as someone pointed
out, have lost the necessary context.

> -Ben

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 3 Mar 2022 15:06:05 +0100

> My opinion is different.  If I followed your approach, a lot of documents would have been delayed and probably abandoned.  

The crucial observation is that different authors have different priorities here.  That is very much OK.
The responsible AD is part of the process to check that it doesn’t derail too much.

> I've been involved as author/editor for a number of multi-hundred-page documents.  The results were not perfect but the documents were improvements over the documents they replaced and that is enough for me.

The perfect is the enemy of the good…

>  should

Did I talk about process confabulation yet today?
I think we are still responsible for the outcomes, even if not everybody else keeps every SHOULD (or MUST).
But that doesn’t mean the result MUST be perfect.

Grüße, Carsten

---

From: Brian E Carpenter <[email-masked]>
Date: Fri, 4 Mar 2022 09:01:52 +1300

David,
On 04-Mar-22 01:08, David Noveck wrote:
...
> The safe thing is to limit changes after consensus to those that do not require such extensive review by the authors who may, as someone pointed out, have lost the necessary context.

This is a bit of a strawman, but it is entirely possible that an editor could resolve an ambiguous sentence in a way that effectively changes the meaning of the whole document; for example, changing a terminology definition that is used throughout the text.

We can't avoid this by issuing meaningless instructions to the editor like "don't change anything that matters". How we resolve it today is by the editor writing to the authors at AUTH48 time in terms like:

4) <!-- [rfced]  We're having difficulty parsing the following sentence
in Section 1.

Original:
    The foo operation includes deleting active state bars.

Perhaps:
    The foo operation consists of deleting all bars that are in the 'active' state.
-->

Only someone who understands the whole scenario can determine whether the second version is a clarification or a change of intent. Whatever the tooling for AUTH48, this sort of edit must be reviewed by a subject matter expert.

    Brian

---

From: John C Klensin <[email-masked]>
Date: Thu, 03 Mar 2022 21:37:38 -0500

--On Friday, March 4, 2022 09:01 +1300 Brian E Carpenter
<[email-masked]> wrote:

>> The safe thing is to limit changes after consensus to those
>> that do not require such extensive review by the authors who
>> may, as someone pointed out, have lost the necessary context.
> 
> This is a bit of a strawman, but it is entirely possible that
> an editor could resolve an ambiguous sentence in a way that
> effectively changes the meaning of the whole document; for
> example, changing a terminology definition that is used
> throughout the text.

Your supposed strawman is eventually what brought us to
pre-publication review of documents that, through a few stages
of review, brought us to AUTH48.  And problems about authors
either tuning out or taking advantage of questionable changes to
substitute their preferences for approving-body consensus.  In
other words "been there, tried that, and it did not work out
well".

Probably worth mentioning that those checks were first put in
place at a time when the editing team had considerably more
expertise and depth about the subject matter of RFCs than
today's RPC and any we are likely to see in the future.    Even
they could got get decisions about what did or did not change
meaning right 100% of the time.

> We can't avoid this by issuing meaningless instructions to the
> editor like "don't change anything that matters". How we
> resolve it today is by the editor writing to the authors at
> AUTH48 time in terms like:
>...

If the editor even notices that a change might be substantive.
The current RPC team gets that right almost all of the time, but
final review by subject matter experts is still important (if
nothing else, to keep this a team effort and avoid pressure on
the RPC for absolute accuracy and universal knowledge.

    john