Re: [Tools-discuss] I-Ds, submission, and preferred formats (detailed response)

[John C Klensin <[e-mail]>]

Hi Jay (and others)

Again, apologies for the slow response.  As noted in the issue
overview I posted within the last couple of hours [0], I'm
sending this note to provide a much more detailed,
point-by-point, response.  Those who are interested only a
summary of that I now think the issues are should read that
early note instead.

I joined this list Wednesday to see the discussion after sending
off what seemed to be some relatively straightforward
suggestions, and got back a very detailed and thoughtful
response from Jay.  Responding to it below; apologies in advance
for length -- the issues are more complex than I had assumed.  I
also suspect there have been some questionable assumptions on
the part of the tools team but only they, and those who have
followed this list longer and more carefully can evaluate that.

Inline below.

[0]
https://mailarchive.ietf.org/arch/msg/tools-discuss/_5qXJ4xRcEDuI-IHN2JMy47r0dY



--On Wednesday, May 25, 2022 10:52 +0100 Jay Daley
<[e-mail]> wrote:

> Hi John
> 
> Thank you for the detailed review - some responses below.
> 
>> On 25 May 2022, at 01:13, John C Klensin <[e-mail]>
>> wrote:
>> 
>> Hi.
>> 
>> I hope this is the right place to make these comments.  If it
>> is not (and maybe it it is), see (1) below.
>> 
>> I had occasion to look at the relatively new authors' [1] and
>> submission [2] pages today.  Nice looking, good explanations,
>> and good work.  I do have some suggestions -- three minor (I
>> hope small patches) and one more substantive.
>> 
>> (1) Minor: Traditionally, a contact address for suggestions
>> and bug reports has been included on every datatracker and
>> other tools page.
> 
> While that may be your impression, I struggle to see evidence
> of such ubiquitous coverage on the tools site.  For example,
> the following page was important source material for this new
> site https://xml2rfc.tools.ietf.org/xml2rfc-doc.html and that
> doesn't have such a contact.

My recollection was that many tools pages used to contain a
contact email address either explicitly labeled as for support
and bug reports or just information about the responsible party
for the page.  See, for example, the home page,
https://tools.ietf.org/, which identifies an update date and
"[e-mail]/.   Similarly, datatracker.ietf.org
contains a link (in red yet) at the bottom for "Report a
bug:...".  Even the mail archive pages have a header with a
"Help" link; clicking on it gets to a page,
https://mailarchive.ietf.org/arch/help/ , which has a "Report a
Bug" entry at the bottom.  While I think it could be better
presented, the IETF home page, www.ietf.org,  at least has a
"Contact" link at the top which leads to
https://www.ietf.org/contact/, which, in turn, provides
information about support information and the [e-mail]
address.    So you may well be correct that coverage on the
tools site was not ubiquitous.  My impression was drawn from a
much larger range of IETF web pages without making the
distinction, resulting in a comment that was not precisely
correct.  But I think it is clear that we maintain problem
reporting information, or ways to find it not more than one
click away, on many IETF pages.  The tools pages we have been
discussing don't seem to come up to that standard.

>>  It is not on either of these and there is no
>> obvious way to get that information.  Unless there is a reason
>> for leaving it out that is not obvious to me, I suggest
>> figuring out a way to restore it.
> 
> Adding this is a good idea - it probably warrants its own page
> so that it is quick and simple to find.  I am happy to provide
> text.  Adding it to the footer of each page is impractical
> given the feature set of the wiki tool.

Just making it easy to find out how to report issues is the
important point.  It own page would be a good idea.  I can even
see advantages in a page that describes all of the contact
addresses for various IETF web page and tools issues and when
each should be used.  The (IMO, very helpful) footer on messages
that passed through this list might be a good starting point but
it does not include that "[e-mail]" address.  I might
expect to see rfc-editor contact information, etc., on such a
page too.  Let's make it as easy as possible for people who get
confused or into trouble to report issues and find help.  The
alternative runs the risk of having them conclude that the IETF
isn't worth the effort -- a problem for newcomers even more than
people who are more experienced and stubborn.

Beyond that, in addition to the constraints of the tool(s), I
find the design of that collection of pages perhaps makes them
easy to read (e.g., for the first time).  But they are, for me,
much harder to use than a design with fewer pages with links
leading back and forth between them if I am trying to find and
extract information (long) after I have a basic understanding of
what is going on and just want to get on with the work.  That
may, of course, just be a matter of taste.

FWIW, a leftover from the days when I was actively involved in
what are now called UX issues is that, when someone says "that
would be the right thing to do" (which you definitely did not
say in this case) "but the tools prevent me/us from doing it", I
find it deeply disturbing.  Again maybe just a personal
idiosyncrasy but something the tools effort might consider. 

>> (2) Also minor:  I would have expected to find a subsection on
>> the authors' page [1] titled something like "Submitting Your
>> Internet Draft" even if all the test says is "When you are
>> ready to have your draft posted, <Submitting your
>> Internet-Draft> [2]".
> 
> There was much community discussion on this list on the best
> way to lead people through the stages and it was agreed to
> have a 'Getting Started" page that set out the steps and with
> links to the detail behind them.  That is at
> https://authors.ietf.org/en/getting-started

Unfortunately, one of the difficulties with this list is that it
is not representative of the broad collection of people who are
trying to develop technical specifications and otherwise make
technical contributions to the IETF.  I am just guessing
(apologies if I'm wrong) that there are also fairly few people
on this list whose professional experience and successful day
jobs are in UX or user interface design and who have
accessibility training, etc.    I assume that many or most of
those on the list are trying to make IETF technical
contributions as well, but there may be differences.  I think
most of us remember the outcry after the fairly recent redesign
of the IETF home page, believing that it was very useful for
newcomers and those trying to learn about the IETF and its
activities, but that it was problematic for experienced
participants, leading to the development of the "Links" page.
That was, IMO, a reasonable solution for both groups but my
point is that the need for the latter apparently came as a
surprise to those who designed and installed the former.  I
looked at the "getting started" page for the first time after
getting your note and it seems completely reasonable as an
approach, especially for newcomers, although it raises some
design and accessibility issues.  The idea of a navigation bar
to the left that is repeated on each of the referenced pages is
a great one, eliminating part of the problems of going back and
forth between the "getting started" TOC and the individual
chapters.  It would be better if it were more obvious that one
needed to scroll it to get to key items and if there were a more
accessible way to do that (e.g., use of a scroll bar that is
invisible unless the cursor is in the right place is typically
fairly useless to someone trying to use a screen reader for
assistance).

If someone were actually going to go through that "getting
started" sequence in order, the individual pages would benefit
from something that is common on the web.  Picking a page more
or less at random from the link collection as an example,
"Required content" might have links at the bottom titled
"Previous: Naming your Internet-Draft" and "Next: Language and
Style" with the obvious arrows.  I don't know whether the tool
kit that was chosen makes that easy, difficult, or impossible,
but please treat it as a suggestion if feasible.

The more important issue for me and perhaps others who have
written and submitted many I-Ds over the years is that, however
useful the "getting started" page may be, it is not the only way
to navigate into this collection.   There are pointers to
individual pages all over the place, including in some of the
transition tools.  The results of searching (from IETF pages or
elsewhere) may lead to pages like https://authors.ietf.org/
(which has that left-hand navigation bar) or
https://author-tools.ietf.org/ (which does not) and not to the
"getting started" one.  Neither of those two "authors" pages
points to the submission tool.  The former does have a pointer
to the getting started page but the line says "Visit
authors.ietf.org for information on how to write an
Internet-Draft" and, as someone who has been writing
Internet-Drafts for 30 or so years now, even if I had noticed
that line, it would not have occurred to me that I needed to go
there to find out about, e.g., draft submission.

>> (3) Another issue/nit: These documents have apparently renamed
>> "xml2rfc" to "RFCXML" even though the relevant RFCs (and even
>> the I-D with the proposed new vocabulary [3]) still use the
>> original terminology.  The only use of "RFCXML" I can find in
>> the datatracker is draft-rfcxml-general-the-new-webiquette
>> [4]. It does not use the term in its actual title or in the
>> body of the document.  It also violates the naming rules for
>> I-Ds.  
>> 
>> It is also not clear from the many contexts in which the new
>> term is used whether it is intended to be a synonym for the
>> "xml2rfc" vocabulary/format, in which case it should appear
>> fairly consistently with a version number unless that is
>> irrelevant or if it refers to version 3, at least unless a
>> version number is given, which appears be the case in some
>> contexts.
>> 
>> I can think of good reasons for the new terminology,
>> especially if you are trying to distinguish between the
>> conversion procedure and the format.  If it is going to be
>> used, please define it precisely and then use it
>> consistently.    However, changes from long-standing and
>> well-established terms to new ones inevitably creates
>> confusion and, in today's world where someone might use
>> xml2rfc as a search term and, sooner or later, won't find
>> relevant pages with it, I think some sort of discussion with
>> the community about the change and tradeoffs would be in
>> order.  Or, if you and others disagree, at least say a bit
>> more than 'RFCXML was previously known as the "xml2rfc
>> vocabulary".' in the body of the "RFCXML overview and
>> background"' page [5].
 
> This has also been discussed extensively on this list.  The
> underlying issue was the confusion between the tool and the
> language because they both shared the same name.  This has led
> to both issues of understanding and issues of design.  An
> example of the former has been the limited use of local schema
> validation, which has also now been addressed through the
> production of templates that automatically support that
> functionality, where it exists.  An example of the latter,
> which is also now largely tidied up, is the use of XML
> processing instructions, which are unique to xml2rfc. 

Again, a reasonable choice going forward, so perhaps the only
problems are that it is probably not adequately described for
those who are used to the old terminology and that it has not
been shared on, e.g., the IETF list rather than only this list.

However, your comment above identifies another issue.   Some
(perhaps few) of us have been constructing I-Ds using xml2rfc
(tool and vocabulary) since 1999.  Probably an even smaller
number had used XML or SGML previously for constructing other
documents and found the IETF mechanisms rather easy to pick up
(the processing directions to which you refer, but that were
easily accommodated in a personal template or two and then
ignored, notwithstanding).  Version 1 and the compilation tool
involved an XML definition with a moderately simple DTD that
made writing and editing with an emacs clone and a handful of
macros fairly straightforward.  No need for XML-specific tools,
no schema, no complicated interactions with libraries and style
sheets that are not obvious to understand (and, AFAICT, not
supported with good quality, accurate, and clear documentation).
I/we adapted to xml2rfc v2 rather easily and are learning to get
along with v3, even while sometimes feeling that parts of it
show signs of second system effect and of moving away from
author-level generic markup and toward format-level
specification.   If the plan is to force me away from my current
way of doing things and into the, IMO more complex, world of
interacting with schema and/or style sheets, well, at best, the
time it would take me to learn things and make that shift (or to
give up on writing XML directly and go to some sort of markdown
or even to the MSWord templates), that time would have to come
away from time I have to do technical, protocol specification,
work and technical document reviews for the IETF.  I am not
convinced that is a good tradeoff.  

Stated more harshly, if the IETF is going to make a decision
that old dogs who cannot, or will not, learn new tricks should
retire and move on, I think that should be a community decision
with an open discussion led by the IESG, not a side effect of
discussions and decisions on this list (or even of some
Consultation).

>> (4) There is an increasing push to submit "RFCXML I-Ds" or
>> "RFCXML" (even that terminology is not completely consistent).
>> The "Submitting..." page [2] uses some fairly strong language
>> like "If an RFCXML submission is not possible..." and "submit
>> RFCXML if at all possible,...".   There is a problem with that
>> recommendation and at least some document authors who are
>> developing directly in that format (I don't have any idea how
>> many of us are left).
> 
> There is nothing new here.  This is taken straight from the
> ancestor I-D Guidelines as written by various community
> members and agreed by the IESG:
> https://github.com/ietf/id-guidelines#the-submission-process

I read that page differently from the way I read the current
submission page.  The statement you cite does say "should be an
xml2rfc version 3 XML source file" (noting that the IESG
apparently has not adopted the new terminology).  But it has
several "if an XML file is submitted" statements in addition to
the one that says "if not possible".   The current web page, by
contrast, seems to me to strongly imply that anyone who cannot
or does not submit RFCXML (v3) source (for whatever reason) is
somehow uncooperative, backward, or not with the program.  I may
be oversensitive about that for the reasons I've given and YMMD
about the interpretation and semantics for other reasons.

>>  When a document, especially a WG one,
>> goes through many iterations, author comments are an
>> invaluable and, at least for me, nearly essential tool for
>> tracking changes, including making notes on when they were
>> introduced and why, and even potential changes.  Those
>> comments are written for authors as notes to themselves and
>> maybe to other authors.  They are not suitable for public
>> availability, especially if they include evaluations of
>> particular ideas or critical comments about the relationships
>> among various suggestions.  And some of the comments are just
>> confusing.   To take a handy example, the working source
>> version of draft-ietf-emailcore-rfc5321bis contains enough
>> information to allow me to identify the source and reasons
>> for most potentially controversial text going back to before
>> RFC 2821 was finalized.   
>> 
>> As the RPC might remember, I started removing all of those
>> comments either before the document went over the wall to them
>> or late in the AUTH48 process, but that means I have to
>> maintain a private working copy and retrofit AUTH48 changes
>> into it to preserve information between RFC-published
>> versions.  In theory, I could do the same thing before
>> submitting each version  -- using an emacs/epsilon macro or
>> private extension to remove all of the comments -- is not
>> that big a deal, but it is extra work. But, unless you want
>> to have a serious conversation about additional tools, I'm
>> going to interpret posting the XML form as "not possible" and
>> you keep getting plain text.  Maybe that is ok, but I want to
>> be sure that the "post XML" near-requirement can be bar to
>> effective and efficient document development and evolution.

> I want to make sure that I understand this correctly - you are
> saying that you have an RFCXML draft that contains comments
> and you do not want those comments included when that draft is
> submitted and so you find it easier to run a conversion to
> Plain Text and submit that than to run a conversion that
> outputs the RFCXML without comments?  (Presumably, because the
> former is a well established workflow and the latter is not?).

Not exactly and my apologies for not being more clear.  As far
as I know, the only point at which archival issues set in for
documents is with the RFC form, not I-Ds.  That has led to my
managing I-Ds for maximum convenience as the documents evolve
during IETF discussion, management that, for me, included many
tracking (and prospective) comments that would be confusing to
others or otherwise unhelpful if made public.  Only at the time
of handoff to the RPC does it make sense to remove those
comments.  Doing so earlier creates a moderately complex and,
IMO, unnecessary, version management problem.

More about that below.

> As I understand it, and emacs is by no means by strong point,
> there is a standard "xml-remove-comments" macro, but if
> that's too long winded then how about a tick box on the
> submission form that says "Remove XML comments" or a new
> function on the Author Tools site that strips comments?

First, I don't actually use emacs on a regular basis but a clone
called "epsilon" that has a different set of built-in functions
and a different extension langueage.  Even when I am using an
editor on a Unix system, emacs has become too feature-bloated
and idiosyncratic for my taste.  I could tailor it to match my
tastes, but using a functionally similar tool with more easily
available capability in some areas has, so far, been easier.
The tastes of others clearly differ.  So, I don't have a
standard "xml-remove-comments" macro.  I have macros of my own
that take comments out, however, they suffer from one of the
same issues that such a function on the Author Tools (or
submission) page would have: I don't want all of the comments
removed.  Some of them contain information that might be useful
to someone trying a successor version from the archival form of
an RFC.   Some are notes to the RFC Editor about choices of
terminology or document structure that have sometimes saved
considerable time during the editing process.  All of those
should remain.  On the other hand, there are also comments
identifying the source (person, date, and reference) of
particular changes or decisions.  Those should probably be
removed to reduce clutter, but there are probably exceptions.
And some are my personal tracking comments and opinions,
reminders of alternatives, prior text that has been changed, and
so forth.  Those comments should come out at RFC submission (or
post-editing) time (but not earlier), even for no reason other
than that, once the document gets IETF consensus, they (and my
notes to myself) cease to be relevant.  And, yes, as I have
hinted, some of those comments were written in haste as notes to
myself and might be considered inflammatory or worse if they
were public.  Those definitely need to come out.

So a simply "take out all the comments" tool won't do it,
whether at the user end or built into the submission process.
For a finished-by-the-IETF document, going through manually with
a good macro that will remove the current comment and go on to
the next one (or just go on), is no big deal and the price I
assume for working, and using comments, that way.   For an
"every time there is a new version of an I-D" process, not very
practical no matter how good that tool is.

Now, if enough people worked the way I do (unlikely) or if we
wanted to facilitate some of the annotations I do/use, it would
be possible to define bits of vocabulary -- elements that could
appear anywhere and that would not produce any output in any
"official" or public rendering.  I'd hope for shorter names, but
imagine elements like
   <DearRFCEditor>
   <TextOrigin>
   <ChangeExplanation>
   <ProposedAlternateText>
   <TicketNumber>
   <Snark>
etc.   Building something that would selectively take those
things out would require only a small matter of programming or a
handful of editor macros.  But I'm not even nearly convinced
that it would be worth it and automatic conversion of existing
documents would be, umm, difficult.   One could do nearly the
same thing by adopting, and keeping to, conventions about how
comments are constructed or tagged internally, but I've tried
that and can't remember my own conventions from one year to the
next (again, not a typical case, but the XML source from which
I'm developing draft-ietf-emailcore-rfc5321bis dates from around
early 2000).

Bottom line: With one exception, I'm not asking that any of  the
tools in that group be changed.  However, I think it is
important that you, and other tools developers, understand that
there are legitimate reasons for not submitting RFCXML for each
new revision / submission of an I-D even if the official
preference is to get that form.

thanks again,
   john
 
>> [1] https://authors.ietf.org/
>> [2] https://authors.ietf.org/en/submitting-your-internet-draft
>> [3] https://datatracker.ietf.org/doc/draft-iab-rfc7991bis/
>> [4]
>> https://datatracker.ietf.org/doc/draft-rfcxml-general-the-new
>> -webiquette/ [5] https://authors.ietf.org/en/rfcxml-overview