Re: Help with tools/process to review a draft

[Warren Kumari <[e-mail]>]

On Wed, Apr 8, 2015 at 8:22 AM, Spencer Dawkins at IETF
<[e-mail]> wrote:
> Just to follow up here ...
>
> On Tue, Apr 7, 2015 at 10:19 PM, Mukom Akong T. <[e-mail]>
> wrote:
>>
>> Thank you all for your valuable help and guidance.
>>
>> On Wed, Apr 8, 2015 at 4:36 AM, Randy Bush <[e-mail]> wrote:
>>>
>>> > I volunteered to review a draft during the last meeting in Dallas. As
>>> > this is my first time, I'd like to get any advice about the most
>>> > effective way to do this:
>
>
> Thank you for volunteering!
>
>>>
>>> focus on the technology, it's correctness, and how well and clearly it
>>> is described.  forget the processes, use whatever tools suit you, the
>>> datatracker will keep track of diffs as the author(s) hack, and you can
>>> report your review via email.
>
>
> I'm assuming that you're volunteering to review a draft within a working
> group.  If you're asking about something else, my answer might be different
> (for example, if you are reviewing for one of the review teams, many of them
> have specific lists of things to look for and prefer that reviews be
> structured in specific ways and sent to specific places.
>
> If you can use plain text email, that works best.
>
> What you find will have an impact on what you do with what you find.
>
> Many reviewers use a "major issues", "minor issues", "editorial issues"
> organization.
>
> As Randy says - focus on technical correctness, and on whether someone who
> isn't currently active in the working group can tell what to do. If you do
> those two things, you have done well.
>
> Anyone CAN review for editorial issues, but if you're seeing major issues,
> please focus on those.
>
> If the approach in the draft just does not work, you can say that, but if
> you're not sure whether there's a problem, you can ask questions. ADs do
> that all the time, for better or worse.
>
> If you find several major issues, you may want to split your review into
> multiple e-mails, to help the working group focus on each issue without
> having to wade through over-quoted text that's not actually being discussed
> at this point in the e-mail thread.
>
> Any draft that the working group sends for publication will have an assigned
> RFC Editor, so if you see editorial mistakes that make the draft unclear,
> please report those, but you don't have to spell-check, verify comma usage,
> etc.
>
> For a working group draft that hasn't been publication-requested, it's best
> to send reviews to the working group mailing list.
>
> If you are only reporting editorial nits, you can send those to the
> editor(s).

And entirely up to you, but sending comments in COPE format (comment,
original, proposed, error[0]) makes life easier for the draft author.

A chunk of text from a draft:
---------------
No special processing is performed by revolvers when serving or
resolving  For all practical purposes CDS is a regular RR type.
---------------

If you just say "You are missing a period and cannot spell", the
author will probably be confused about where exactly you are talking
about.

Sending:
O: "No special processing is performed by revolvers when serving or
resolving  For all practical..."
P: "No special processing is performed by resolvers when serving or
resolving.  For all practical..."
C: Missing period between 'resolving' and 'For'. Also, I'm assuming
you meant 'resolvers', not 'revolvers'. :-)

will make the author's live *much* easier - they can search and find
the original error, and know what exactly you are referring to.

Author's brains often do autocorrect on their own text, and so they
miss "obvious" errors - for example, the "revolvers" example above
comes from one of my drafts -- the error came in in version -00, and
survived much careful review, finally only being noticed in -13 [1]
:-)

Almost all authors (and working groups) will be very grateful for
whatever review you do, and will be happy to take comments in whatever
form you choose. One thing that it worth keeping in mind is that you
may get responses back that sound "grumpy" or argumentative. This is
almost always simply part of the debate culture in the IEFT (and / or
is the author trying to make sure he fully understands your point),
and isn't intended to be grumpy towards the reviewer... although some
people *are* just jerks.

W

[O]: This is usually just used as OPC form (not COPE), but, well, COPE
sounded better (thanks to Tony Finch for suggesting the acronym).
[1]: https://tools.ietf.org/html/draft-ietf-dnsop-delegation-trust-maintainance-13#section-3.1

>
>>>
>>> > I'm probably over-thinking this
>>>
>>> you are.  but doing so seems to be a vital skill in the ietf :)
>
>
> Ideally, not all Nomcoms select for that ...
>
> Spencer
>



-- 
I don't think the execution is relevant when it was obviously a bad
idea in the first place.
This is like putting rabid weasels in your pants, and later expressing
regret at having chosen those particular rabid weasels and that pair
of pants.
   ---maf