Bob Braden wrote:
> I expected you to object to the removal to "NAPTR RR" from the first
> sentence; I myself would agree that this removal was erroneous editing.
Hmmm... I feel an update to this spec coming on ;-)
> The original sentence did not make sense (to me), while your final
> corrected sentence does make sense. If we had not made the AUTH48
> change, the original nonsensical sentence would have persisted.
But only because I caught it -- or else it would have gone out
saying the wrong thing.
And given the choice between a *possibility* of being misunderstood
or having the document going out stating the wrong thing, albeit
with improved clarity -- well, there is a certain sense in the
community that the 1st option is the winning one.
Note that, for the first case, I, as author of the specification, must
bear responsibility. The latter appears to happen due to some magical
force that has acted upon the text.
My very personal opinion:
I, as an author, read the AUTH48 diffs diligently. It doesn't
always happen on all documents though, and the IETF doesn't have a clear
way of dealing with that in producing its specs. Also, dealing with
these issues at the tail end of the process, in a blackbox,
depersonalized exchange with [email protected] is *stressful*
to authors. "I place my changes upon the stone steps and hope they will
be accepted"...?! Perhaps it's not a lot less stressful on the other
end of the exchange, either.
Note that I *fully* appreciate having issues in my text flagged.
My *personal* preference is to have editing happen earlier in the
process, and more interactively. "Hey, Leslie, I can't understand
what the HECK you're trying to say in this sentence; how about
this?". Note that I was not one of the authors/editors
who got to participate in the early editing experiment, but I really
am hopeful for integrating more of that sort of thing into our
overall process.
But, if we can't, the IETF needs to make a decision about
whether it will sacrifice potential clarity for possible error.
Here's another example from that same document/exchange.
Note that I'm not really convinced the final version was a lot
clearer, but it's what the RFC Editor put in the document. I
kinda was left wondering if I'd won the point or the RFC Editor
gave up arguing with this pesky author.
AUTH-48:
6.3. Expected Output
The expected output of this application is the information necessary
for an application service within a given domain to connect to
authoritative server(s) (host, port, protocol).
ORIGINAL:
6.3 Expected Output
The expected output of this Application is the information necessary
to connect to authoritative server(s) (host, port, protocol) for an
application service within a given a given domain.
ISSUES:
First, the "Application" refers specifically to a DDDS Application, not
to any random generic application. Therefore, here (and in the several
other places you've changed "Application" to "application"), it
should either revert to "Application", or be changed to "DDDS
Application".
More importantly, for this paragraph -- the meaning has been completely
changed. The original described [a little-a application] connecting to
an authoritative server within a domain. The AUTH-48 describes an
authoritative server connecting to a server within a domain, which
is nonsense. If the rewrite below seems complex & tortuous -- well,
I don't think it's a language problem, it's just what this stuff is.
NEW:
6.3 Expected Output
The expected output of this Application is the information necessary
for a client to connect to authoritative server(s) (host, port,
protocol) for a particular
application service within a given domain.
Leslie.
Leslie,
You wrote:
*>
*>
*> The quoted requirement is not something that you can split
*> and interpret separately as you have done in your comment.
*>
*> Yes, RFC Editor certainly routinely catches issues of readability,
*> greater and lesser. AUTH48 is always (at least, for me :-) )
*> an exercise in learning how unclearly one writes ;-) And,
*> there was a notable instance when the RFC Editor caught the fact
*> that my document had 2 non-sentences trailing at the end of
*> a section -- leftovers from previous edits. I had not caught
*> that. The IETF-wide last call had not caught that. The IESG
*> review had not caught that. Oops on all of us :-)
*>
*> But.
*>
*> "that may change technical ... wording" is key. Too often
*> "clarity" breaks the intended meaning.
*>
*> A simple sample, from my own experience:
*>
*> ORIGINAL:
*> 2.2.4 S-NAPTR and Successive Resolution
*>
*>
*> As shown in the example NAPTR RR set above, it is possible to have
*> multiple possible targets for a single application service+protocol
*> pair. These are to be pursued in order until a server is
*> successfully contacted or all possible matching NAPTR records have
*> been successively pursued to terminal lookups and servers contacted.
*> That is, a client must backtrack and attempt other resolution paths
*> in the case of failure.
*>
*>
*> AUTH-48:
*> 2.2.4. S-NAPTR and Successive Resolution
*>
*> As shown in the example set above, it is possible to have multiple
*> possible targets for a single application service+protocol pair.
*> These are to be pursued in order until a server is successfully
*> contacted or all possible matching NAPTR records have been
*> successively pursued to terminal lookups and contacted servers. That
*> is, a client must backtrack and attempt other resolution paths in the
*> case of failure.
*>
*>
*> ISSUE:
*> The binding of "all" has failed, in rewriting "servers contacted"
*> to "contacted servers".
*>
*> NEW:
*> 2.2.4. S-NAPTR and Successive Resolution
*>
*> As shown in the example set above, it is possible to have multiple
*> possible targets for a single application service+protocol pair.
*> These are to be pursued in order until a server is successfully
*> contacted or all possible matching NAPTR records have been
*> successively pursued through terminal lookup and server contact. That
*> is, a client must backtrack and attempt other resolution paths in the
*> case of failure.
*>
*>
The original sentence did not make sense (to me), while your final
corrected sentence does make sense. If we had not made the AUTH48
change, the original nonsensical sentence would have persisted.
I expected you to object to the removal to "NAPTR RR" from the first
sentence; I myself would agree that this removal was erroneous editing.
Bob Braden
_______________________________________________
Techspec mailing list
[email protected]
https://www1.ietf.org/mailman/listinfo/techspec
