Subject: Help with tools/process to review a draft

From: "Mukom Akong T." <[email-masked]>
Date: Tue, 7 Apr 2015 23:57:32 +0400

Hello,

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:

- is there a recommended process?
- are there recommended tools (i assume plain text editor)
- how do I track changes? (apart of a diff of both files)
- how do I report back to the WG the results of my review?

I'm probably over-thinking this but I'll gladly take all the help I can get.

-- 

Mukom Akong T.

http://about.me/perfexcellence |  twitter: @perfexcellent
------------------------------------------------------------------------------------------------------------------------------------------
“When you work, you are the FLUTE through whose lungs the whispering of the
hours turns to MUSIC" - Kahlil Gibran
-------------------------------------------------------------------------------------------------------------------------------------------

---

From: Riccardo Bernardini <[email-masked]>
Date: Tue, 7 Apr 2015 22:05:13 +0200

About the editor: I assume your "source" is the XML format.  Any editor
will do, but I would suggest some editor with features for XML.

My (strictly personal) preference: although I am mostly a emacs user (who
writes his own macros), for XML files I like jedit, a Java-based editor
with nice XML features (although a bit heavy on the CPU).

Riccardo

On Tue, Apr 7, 2015 at 9:57 PM, Mukom Akong T. <[email-masked]>
wrote:

> “When you work, you are the FLUTE through whose lungs the whispering of
> the hours turns to MUSIC" - Kahlil Gibran
>

---

From: Randy Bush <[email-masked]>
Date: Wed, 08 Apr 2015 09:36:03 +0900

> 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:

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 probably over-thinking this

you are.  but doing so seems to be a vital skill in the ietf :)

randy

---

From: "Mukom Akong T." <[email-masked]>
Date: Wed, 8 Apr 2015 07:19:37 +0400

Thank you all for your valuable help and guidance.

-- 

Mukom Akong T.

---

From: Spencer Dawkins at IETF <[email-masked]>
Date: Wed, 8 Apr 2015 07:22:16 -0500

Just to follow up here ...

>> > effective way to do this:
Thank you for volunteering!

>> 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).

>> you are.  but doing so seems to be a vital skill in the ietf :)
Ideally, not all Nomcoms select for that ...

Spencer

---

From: Dave Crocker <[email-masked]>
Date: Wed, 08 Apr 2015 07:11:07 -0700

> Many reviewers use a "major issues", "minor issues", "editorial issues"

It helps to start with a /very/ concise summary of the nature of the
document.  What is it for?  What does it do?  How does it do it?  This
establishes that your understanding of the document matches what the
author(s) intended.

My own approach to commenting, after that, is to summarize the major
issues in some free text, after the summary, and then to provide a
single set of in-line comments of the document.

d/

-- 
Dave Crocker
Brandenburg InternetWorking
bbiw.net

---

From: Warren Kumari <[email-masked]>
Date: Wed, 8 Apr 2015 11:10:26 -0400

On Wed, Apr 8, 2015 at 8:22 AM, Spencer Dawkins at IETF
<[email-masked]> wrote:
> (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
> 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.
>

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 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

---

From: "Mukom Akong T." <[email-masked]>
Date: Thu, 9 Apr 2015 22:22:18 +0400

Thank you all. Your comments have been very useful and I'm definitely going
to volunteer again to get some practice doing this.

Regards

On Thu, Apr 9, 2015 at 9:36 PM, Elwyn Davies <[email-masked]> wrote:

>
>
> On 08/04/2015 04:19, Mukom Akong T. wrote:
>
>   +1
> You can find lots of examples of reviews (and how comments get resolved -
> or not - sometimes it's a matter of opinion!) in the various IETF mailing
> list archives:
> Reviews from 'directorates' done towards the end of the process - forget
> the process and feel the comments:
> 'Generalist' reviews trying to make sure that people other than subject
> matter experts will be able to make good use of RFCs:
> http://www.ietf.org/mail-archive/web/gen-art/current/maillist.html
> Reviews by area 'experts' not originally involved in writing the draft
> (e.g., security in this case):
> https://www.ietf.org/mail-archive/web/secdir/current/maillist.html
> And examples of comments on specific drafts by WG participants in pretty
> much any WG mailing list archive:  http://datatracker.ietf.org/list/wg/
>
> Again, thanks for volunteering.
>
> Cheers,
> Elwyn
>

-- 

Mukom Akong T.

---

From: Elwyn Davies <[email-masked]>
Date: Thu, 09 Apr 2015 18:36:32 +0100

On 08/04/2015 04:19, Mukom Akong T. wrote:
> On Wed, Apr 8, 2015 at 4:36 AM, Randy Bush <[email-masked] 
> <mailto:[email-masked]>> wrote:
>
+1

You can find lots of examples of reviews (and how comments get resolved 
- or not - sometimes it's a matter of opinion!) in the various IETF 
mailing list archives:

Cheers,
Elwyn

---

From: Abdussalam Baryun <[email-masked]>
Date: Sat, 11 Apr 2015 08:04:22 +0200

Hi Mukom,

I agree there should be a review process but I think it is very
free/flexible in IETF. My confusion when I first reviewed and participated,
was that I didn't get any respond from authors/editors (even if I put it on
the WG list), some time they wait for discussions which is not a good
practice/process and few times they just ignore to reduce the discussion
traffic related to their draft. The most important process in IETF is the
discussions on the draft's WG list. I remember that the Routing Area
Director replied to me that if there is no reply then I can send him a
message for requesting a reply. Therefore, my advise/suggest for the best
practice is:-

1- We are part of IETF, so Your reviews and Comments are important and are
part of the IETF-process, but only when you send it to IETF addresses or
when you present them in IETF meetings.
2- Make your draft review present to the discussion lists (WG list even if
not requested, or to IETF list if requested by IETF last call).
3- You MUST get a reply from at least one participant or one editor/author,
and make discussions. That can be tracked by the sender.
4- If no reply, send a message to the WG Chair and the AD (to their ietf
addresses), because they SHOULD follow up with the WG-process.
5- Each IETF list needs to have some one that volunteers to look into
reviews and reply to build discussion or to guide for draft-edits.
6- Make your changes to the draft and don't wait for editors to change the
draft, just write OLD statements, and NEW statements. The editors MUST
follow your changes in the next revision if there was no objections.
7- The IETF tools are still under development, and your/our reviews to
tools are recommended as well :-). There is no track of plans or
discussions, sometimes the meeting minutes miss some points, however, we
SHOULD volunteer to make our work more track able.

Thanks,

AB

---

From: Matt Mathis <[email-masked]>
Date: Sat, 11 Apr 2015 08:48:26 -0700

All good advice all around.

> As Randy says - focus on technical correctness,
>

I generally agree, however I have seen at least one case where bad grammar
was covering ambiguous/inconsistent meaning, such that after the grammar
was corrected, the reviewer and author discovered that they were not in
agreement.

Thanks,
--MM--
The best way to predict the future is to create it.  - Alan Kay

Privacy matters!  We know from recent events that people are using our
services to speak in defiance of unjust governments.   We treat privacy and
security as matters of life and death, because for some users, they are.

On Thu, Apr 9, 2015 at 11:22 AM, Mukom Akong T. <[email-masked]>
wrote:

> Thank you all. Your comments have been very useful and I'm definitely
> going to volunteer again to get some practice doing this.
>
> Regards
>