Required doc sections (Re: [saag] Next step on web phishing draft(draft-hartman-webauth-phishing-05.txt))

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



> > My position is the exact opposite. Full and complete review of drafts it of
> > paramount importance and anything thqt interferes with that is unacceptable.
> > And as I have pointed out, we have "running code" demonstrating that these
> > things are at best distracting and at worst actively interfere with proper
> > review.

> > What's appropriate to appear in the final RFC is up to the RFC Editor. That's
> > what the word "editor" implies. If the RFC Editor deems it appropriate to
> > remove null sections that's fine, if they feel they should be retained that's
> > fine too. Someone reading an RFC to learn how to implement something has a
> > definite goal in mind and isn't going to be (or at least shouldn't be)
> > distracted by boilerplate in the same way a reviewer looking for issues - a far
> > more nebulous proposition - can be.
> >

> Well, I guess we do disagree here to some extent.  For me, every
> sentence of a document that doesn't contribute to the technical
> knowledge that needs to be conferred, interferes with readability, and
> ultimately, interoperability.

I think this is absolutely true of drafts - the target audience is composed of
people with substantial expertise in networking and who are tasked with finding
any potential problems that cound arise, including obscure ones.

In the case of RFCs things aren't so simple. The RFC Editor has to balance a
wide variety of competing and sometimes conflicting goals, including but not
limited to keeping the publication series as a whole consistent, making sure
intellectual property concerns are addressed, seeing that neophytes aren't
misled and insuring the material is laid out sensibly. A substantial amount of
both expertise and perspective is required - something individual authors
cannot be relied on to have.

The IETF has a whole has an unfortunate tendency to want to second guess the
RFC Editor in a lot of this. IMO this tendency is something we need to resist.

> That applies to the copyright
> boilerplate, that applies to checkoff sections that are just there to
> get approval, it applies to information that is needed only by IANA.
> And I wasn't aware that our processes allowed the RFC Editor to delete,
> say, a meaningless IANA considerations section.  (I've never checked to
> see whether has happened.)

My undestanding is that it happens all the time. (I cannot speak from personal
experience because of late all of the documents I've dealt with have had
non-null IANA considerations.)

> However I don't have a problem with IESG wanting additional supporting
> information to help it decide whether to approve documents and to decide
> what additional processing is needed.  If the best place to put such
> information is in the I-D, fine; if the best place to put that
> information is in a separate form, that's also fine with me.  (And I'd
> far prefer that we not impose unnecessary burdens on authors of early
> I-Ds - the fewer hoops they have to jump through, the better.)

This is the heart of the issue. I think having IANA considerations on
a separate checklist is an excellent idea, with two possible
answers: (1) The document has IANA considerations and they are
described in an IANA considerations section and (2) The document has
been checked and found not to have any IANA considerations.

The key difference here is _when_ this information is provided. A submission
form isn't going to  be filled out in advance so there's a good chance it will
relect the current state of the document. A null IANA considerations section
that's in the document will likely as not be there from the start, and if it
doesn't get updated it becomes an active source of confusion.

> In general, I think that I-Ds and RFCs really serve very different
> purposes, and trying to make them be (almost) the same causes us to make
> less readable end product.

Agreed, although I really don't know what can be done about it that we're not
already doing.

> I'd like to see more use of "NOTEs IN DRAFT"
> and similar devices to separate supporting material from material that
> belongs in the final publication.

Having a single section of this sort is fine and something I and lots of others
do fairly routinely, if for no other reason than to keep track of changes to
the draft. But beyond that I think there are dragons lurking -  having such
notes scattered throughout the document is bound to cause confusion about
what's supposed to be in the published RFC.

I will also say that while having crisp technical content is of paramount
importance, RFCs are used for lots of purposes and our aversion to providing
more than a bare minimum of contextual information is in many cases quite
counterproductive. A lot of our documents would be improved tremendously by
having nonnormative "how we got to this point" appendices in the published
version.

> I'm concerned about readability
> throughout the document cycle, but am especially concerned about
> readability of our published documents - as many more people read them
> at this stage and those people have less context to aid them in sorting
> through the crap.

Well, in the abstract sense of course I'm more concerned about the published
document. But IMO a significant fraction of the responsibility for that has to
be - and in practice is - borne by the RFC Editor. It is therefore appropriate
for authors to focus on making their drafts maximmally suitable for the part of
the process the IETF is responsible for - getting the technical content right.

				Ned

_______________________________________________

Ietf@xxxxxxxx
https://www1.ietf.org/mailman/listinfo/ietf

[Index of Archives]     [IETF Annoucements]     [IETF]     [IP Storage]     [Yosemite News]     [Linux SCTP]     [Linux Newbies]     [Fedora Users]