[rfc-i] normative (and vetted) text vs. diagram (was Re: Fwd: New Version Notification for draft-flanagan-plaintext-00.txt

Dave Crocker dhc at dcrocker.net
Thu Jun 26 07:59:12 PDT 2014


> If I have understood correctly and we have to continue doing ASCII
> art or add in many more words for such cases, I am not sure this is a
> gain.


> The limitations of ASCII art are one of my major annoyances with 
> ietf document format. A common form that is problematic is a state 
> transition diagram. Not only are these hard to draw, but when they 
> get beyond a minimal level of complexity they are very hard to fit 
> with current line length limitations and remain easy to understand.


> Any item that has more than one representation begs the question of
> "which is normative?" *when* (not if) the text and figure differ.



When we did DKIM-bis, I was impressed to find a couple of places where
the ABNF and associated text differed significantly, where one was
essentially accurate and the other was substantially not.

Besides the problem this poses for a new -- and therefore naive --
reader of a spec, it points to a pretty serious and basic failure in the
IETF's QC processes.  DKIM had extensive participation by a wide range
of people, including experienced IETFers.  The document was /very/
heavily reviewed.

Yet impressively basic documentation -- not protocol -- errors existed
in the text, in exactly the kind of circumstance we are now discussing.

Creating a strong bias against having any ascii art is a large strategic
change.

Moving towards declaring diagrams never normative is a very large
strategic change.

We should not back into these changes without explicit community
discussion and a much better understanding of the collateral effects.


We need to be clear about the long-standing benefits of txt-formatted
RFCS and we need to retain that utility.  This includes ascii art.

No it is not fun to produce ascii art and yes it has limitations.
Neither point is irrelevant but neither do they justify deprecating a
form that has been so spectacularly successful.


My own suggestion is:

0. If there is artwork, there must be an explicit review effort to
reconcile art with the associated text.

1. If there is a artwork, there must be an ascii art version.

2. If there is a non-ascii version of art, the ascii version may be a
'low resolution' form, simplified to be tolerable within the constraints
of ascii art.

3. If there are two versions of art, the ascii art version must
explicitly label itself as non-normative.  (I'm not happy about this
suggestion, but we need to deal the certainty of disparity.)


d/
-- 
Dave Crocker
Brandenburg InternetWorking
bbiw.net


More information about the rfc-interest mailing list