Re: Guidelines for authors and reviewers

[SM <[e-mail]>]

Hi Suresh,
At 14:42 30-05-2008, Suresh Krishnan wrote:
>I do share your sentiment, but this is not what we set out to do
>originally. We set out to document the review process(es) and provide
>some guidelines to effectively use the received reviews. I think the
>right document to weave the stuff together would be the Tao. But I do
>agree that adding references to the Tao and 2026 make sense. The
>dangling reference to 2119 is an editorial oversight :-).

I commend the authors for writing this document even though it will 
most likely attract the attention of the IRS^H^H^H IETF audit team. :-)

Quoting RFC 2555:

   "It has been ultimately fascinating to watch the transformation of the
    RFCs themselves from their earliest, tentative dialog form to today's
    much more structured character."

   "As the Internet has taken on greater economic importance, the standards
    documented in the RFCs have become more important and the RFCs 
more formal."

The Tao has an air of formality in some places.  It will be 
interesting to watch the transformation of this document as it moves forward.

An author needs to have both technical and social skills to see a 
document through the RFC process.  The Document Lifecycle tutorial 
covers the technical points required to produce a RFC.  Your I-D 
focuses on the second aspect.  One of the things I've learned is that 
it's not easy to apply rules there as we have to take the people 
element into account.  Even guidelines can have a detrimental affect 
as some people may read them as rules.

In Section 1:

   "An Internet Draft's life cycle begins when the author(s) submit the
    document as an individual submission"

That may lead to some confusion with independent submissions.  It may 
be better to have:

   "An Internet Draft's life cycle begins when the author(s) submit 
the document
    as a personal draft; it may become a Working Group draft, and usually ends
    when the draft is published as an RFC, or is abandoned and 
eventually expires."

Comments are generally sent either directly to the author(s) or to a 
mailing list.  There may be frustration on both sides as some 
reviewers may expect a personal reply.  The authors can be busy 
people and may not have the time to answer each individual 
email.  Sometimes it's easier for them to post a reply to a mailing 
list for issues about a Working Group document instead of responding 
to the same questions over and over again.

I suggest using "Internet-Draft" and "Last Call" throughout the document.

Section 2 (Sources of reviews) might benefit from some references to 
the Tao to expand on the review process as the document goes through 
the various stages.

In Section 3.1:

   "There are several persons who can respond to a received review.  If
    the document is an individual document"

I suggest using the same term as the RFC Editor.

    There are several persons who can respond to a received review.  If
    the document is an independent submission

In Section 3.3, you mention "every review merits a response."  In my 
personal experience, most authors send a response which may contain a 
question or a note.  Should I label the minute few who don't respond 
as lacking common courtesy? :-) I don't think so (see my comment 
about authors being busy).

In Section 3.3.1, you spell out a time frame for the authors to 
respond.  Some authors take an approach where they wait for the heat 
to turn down or wait for the usual suspects to respond before sending 
in a substantive response to cover the points raised.  It's difficult 
to set an acceptable time frame as some debates can be quite lengthy.

In Section 3.3.3.1:

    "It would be nice for the author to come up with a timeline on when he/
     she would be able to respond to the comments/issues contained in the
     review."

The author may be doing this work on a voluntary basis.  Although 
it's nice to have a timeline, it pressures the author to respond by that date.

In Section 3.3.3.3, there is:

   "However, often that explanation should really be in the draft itself,
    not just in emails to the authors, so that future readers will also
    understand the text."

The longer a document is, the less people are inclined to read it 
thoroughly.  It's a balance between what to put in the document while 
keeping it within an acceptable size.  An explanation is not put in 
because the reviewer did not understand some part of the draft; it is 
added to provide context or a rationale and make the specifications 
clear-cut.  Otherwise, the document would turn into a tutorial.

   "Soliciting text from the reviewer should be used sparingly."

The reviewer should also be part of the participative effort.  That's 
why there is "send text".  Else, the author has to second guess 
what's in the reviewer's mind which is no easy task.  It also makes 
it difficult to quell arguments as there may be people who disagree 
without proposing any resolution.

In Section 3.4, there is:

  "this is buy using"

In Section 3.5:

   Once the author feels that all the open issues have been addressed he/she
   can submit a new revision of the draft that incorporates the changes.

Section 3.6 mentions Acknowledgements.  The contributor is not only 
mentioned in a RFC out of politeness.  There may be an overlap with 
other IETF documents if you get into that.

Trivia, there was a recent I-D that contained a love note. :-)

I hope that this email is not a disheartening read.  Some of the 
ideas in the I-D are excellent.  Whether they are practical is 
another question.  Even though you are the authors, the onus of 
refining the document should not rest on you alone.  You raised 
several points which may be on the minds of the silent majority that 
follow the IETF mailing lists.

Regards,
-sm 

_______________________________________________
IETF mailing list
[e-mail]
https://www.ietf.org/mailman/listinfo/ietf