Subject: Re: WG ACTION: 2 weeks to discuss [LL60] Forward reference style

From: Stuart Cheshire <[email-masked]>
Date: Thu, 6 May 2004 22:52:08 -0700

>While it's not a big deal, the statement "This is standard practice in all
>RFCs that include constants" can be disproven by counterexample; RFC 3315
>defines all of the symbolic constants in an early section before any of
>those constants are referenced in the specification.
>
>I suggest simply moving section 9 so that it appears before any of the
>defined symbolic constants are first referenced.

Thank you Ralph. Hopefully my proposed changes for LL53 address this.

Robert Elz wrote:

>RFCs are for implementors, not for people learning.   Implementors, if
>not necessarily experts, should at least be competent.  If someone wants
>to publish a book "IPv4 link local addresses for morons" (or whatever)
>then they can do it in a way which manes it easy for beginners to
>learn the protocol.   The RFC doesn't need to do that.

I cannot fathom this point of view.

The first time someone reads any document, including an RFC, they're 
learning what the document says.

What possible reason would we have to NOT make an RFC as clear and 
understandable as possible?

Stuart Cheshire <[email-masked]>
 * Wizard Without Portfolio, Apple Computer, Inc.
 * www.stuartcheshire.org

---

From: Robert Elz <[email-masked]>
Date: Sat, 08 May 2004 02:24:15 +0700

Date:        Thu, 6 May 2004 22:52:08 -0700
    From:        Stuart Cheshire <[email-masked]>
    Message-ID:  <[email-masked]>

  | What possible reason would we have to NOT make an RFC as clear and 
  | understandable as possible?

None.   And if you had raised some of you points when the doc was
being debated, I'd be agreeing with more of them - even if it had been
done during the last call.   But that isn't what happened.   Now it
just looks like an attempt to delay a doc that you don't really like for
as long as possible in the hopes that it will end up being so late as
to be useless.   Much better to publish what we have now.  If necessary
after experience with it, a clearer doc can be made part of advancing
this from PS to DS (or whatever the standards process migrates into,
assuming that it may eventually alter).

That said, I actually don't agree that putting const definitions at the
front makes the text easier to understand.   For me, it makes it harder.
When I see a bunch of definitions like that, I immediately find myself
jumping to conclusions about how they're going to be used, and inventing
my own imaginary protocol to use the things as I have dreamed them.
That then makes actually understanding what is written harder, as I'm
constantly prejudiced by my earlier imaginings about how the whole thing
is going to work.

So, even if there was some desire to make things better, and some text
was going to be changed, the very most I'd want would be a forward
reference in the introduction - something along the lines of "Symbolic
constants will be used throughout this document, to determine the
values of those constants, refer to section 9".

And then, when I read the doc, initially (not actually doing an
implementation) I avoid looking forward at the values, as 99% of the
time, knowing the actual numbers helps with nothing (short of
implementing it).

But at this stage in the processing of this doc, I don't want even that.

kre