Subject: Document language editing session in London

From: Ted Lemon <[email-masked]>
Date: Thu, 16 Jan 2014 19:03:52 -0800

Dear WG Chairs:

The IESG has decided to repeat the experiment that we tried in Berlin at the upcoming London IETF meeting.   We would like to invite ten document authors to a language editing session in London on the Saturday prior to the IETF meeting.   The goal of this editing session will be for two area directors, me and Joel Jaeggli, to each sit with a group of five document editors and work on each editors' document for 30 minutes in a group setting.   Benoit Claise has also offered to help if there are any French-speaking authors who would like to participate.

The plan for this work is to do two things: first, to review the documents, and secondly, for the participants to have the opportunity to work with Joel or with me to improve the quality of their documents.   The goal is specifically for non-native english speakers who have documents that the working group considers important, but which are felt to need help with english language editing.   It is important that the authors _want_ to get help—that they recognize that they could use help and that they are comfortable getting that help in a small group setting.

What the meeting will look like is that there will be one or two tables in a meeting room; I will be at one table with five authors and a representative from the RFC Editor.   Joel will be at a separate table, with the same arrangement.   If there aren't enough authors, we may do a single table, as we did in Berlin.

Each of us will have briefly reviewed the five documents prior to the meeting, and we expect that the authors will be familiar with each others' documents as well.   For thirty minutes per document, we will sit with the author and go over the document, offering comments and suggestions and getting feedback from the author.   The other authors will follow this. Then we will move on to the next author.   Joel will be doing the same thing at the other table.   The RFC Editor will be observing and offering advice on request, or if they can't resist, but the main goal is to take advantage of the technical editorial expertise of the two ADs for this experiment.   At the end of the editing session, we will have a half hour session where we talk about what went well, if anything, and what went wrong, if anything, and how we might do it better next time.

Neither Joel nor I are experts on teaching english to non-native speakers, so we do not claim any specific knowledge other than that we both have a keen interest in improving the quality of IETF documents, a fair amount of experience in at least trying to do so, and a desire to help our colleagues to accomplish their goals.

Our desired outcome from this meeting is twofold: first, to help the specific authors who attend; secondly, to learn how to help authors in general: what frustrations they have in writing documents for IETF, what stumbling blocks they trip over, and how we can help them.

What we are asking working group chairs to do is think about whether there are documents in their working group that could use this sort of help.   If you believe there are, please contact the authors of those documents and ask them in a non-pushy way whether they would like to participate in this experiment.   Please let us know if any of your authors are interested in this.   If you have more than one document that you'd like worked on, please tell us which one is most important to you.   We will have to do a triage process unless the response to this call for participants is tiny, so it's likely that we will only take the document you think is more important.   If we get a really good response, we won't be able to take documents from every working group that responds; please don't take this as a criticism if your document isn't chosen.

If you think this is a good idea and want to take advantage of it, please contact your authors as soon as possible, so that they can make travel plans that allow them to get to the venue on Saturday rather than on Sunday.   Please bear in mind that the document selection process will take time, and set your authors' expectations appropriately.

We will arrange for authors who wish to attend and who are selected to receive invitations, so that they can justify the early arrival to their management if necessary.

Thanks!

---

From: Michael Richardson <[email-masked]>
Date: Fri, 17 Jan 2014 11:21:17 -0500

Ted Lemon <[email-masked]> wrote:
    > The IESG has decided to repeat the experiment that we tried in Berlin
    > at the upcoming London IETF meeting.   We would like to invite ten
    > document authors to a language editing session in London on the
    > Saturday prior to the IETF meeting.   The goal of this editing session
    > will be for two area directors, me and Joel Jaeggli, to each sit with a
    > group of five document editors and work on each editors' document for
    > 30 minutes in a group setting.   Benoit Claise has also offered to help
    > if there are any French-speaking authors who would like to
    > participate.

So, it's aimed at non-english document editors.
WG chairs should consider where to apply this careful --- laser precision here.

(In my WG, I think that we have most of the non-english first language
speakers have self-selected themselves out of being document editors; we do
have lots of individual submissions, and I think that some of the barrier to
adoption is language.
Mind: we have quite a few french-as-first-language contributors, but one
hardly notices that until you talk to them)

    > What we are asking working group chairs to do is think about whether
    > there are documents in their working group that could use this sort of
    > help.   If you believe there are, please contact the authors of those
    > documents and ask them in a non-pushy way whether they would like to
    > participate in this experiment.   Please let us know if any of your
    > authors are interested in this.   If you have more than one document
    > that you'd like worked on, please tell us which one is most important
    > to you.   We will have to do a triage process unless the response to
    > this call for participants is tiny, so it's likely that we will only
    > take the document you think is more important.   If we get a really
    > good response, we won't be able to take documents from every working
    > group that responds; please don't take this as a criticism if your
    > document isn't chosen.

Thank you for this.
I hope that it will be repeated several times.

--
]               Never tell me the odds!                 | ipv6 mesh networks [
]   Michael Richardson, Sandelman Software Works        | network architect  [
]     [email-masked]  http://www.sandelman.ca/        |   ruby on rails    [

---

From: Michael Richardson <[email-masked]>
Date: Fri, 17 Jan 2014 11:28:16 -0500

Thank you for this.

--
Michael Richardson <[email-masked]>, Sandelman Software Works

---

From: Thomas Narten <[email-masked]>
Date: Fri, 17 Jan 2014 11:49:01 -0500

> The IESG has decided to repeat the experiment that we tried in

Is there a report or summary of the what was learned from that
experiment?

While I have to support the goals of this effort, it surprises me that
ADs are doing the leg work here.

With all due respect, aren't ADs chronically overloaded and short on
cycles to do more important things? I'd be suprised if only ADs can
take on this particular task, and if other volunteers can't be found,
that might say something about how important the community feels this
issue is.

Improving writing skills of non-native english speakers is a generic
problem, hardly  specific to the IETF.

Thomas

---

From: Zongning <[email-masked]>
Date: Sat, 18 Jan 2014 02:58:31 +0000

Dear Ted, and all,

As a non-native English speaker, I agree that this is a good practice to improve the quality of IETF I-Ds.

I also share the opinion of Thomas that more volunteers should be called to help the whole community. Probably the similar practice could be conducted in a more "distributed" way, e.g., in WG level, led by WG co-chairs.

Anyway, I will plan to submit I-D to this session in London, learn something important, then talk to my group, especially as a non-native English WG co-chair. :-)

Thanks.

-Ning

> -----Original Message-----
> From: WGChairs [mailto:[email-masked]] On Behalf Of Ted Lemon
> Sent: Friday, January 17, 2014 11:04 AM
> To: [email-masked] Chairs
> Cc: Heather Flanagan (RFC Series Editor)
> Subject: Document language editing session in London
> 
> Dear WG Chairs:
> 
> The IESG has decided to repeat the experiment that we tried in Berlin at the
> upcoming London IETF meeting.   We would like to invite ten document
> authors to a language editing session in London on the Saturday prior to the
> IETF meeting.   The goal of this editing session will be for two area directors,
> me and Joel Jaeggli, to each sit with a group of five document editors and work
> on each editors' document for 30 minutes in a group setting.   Benoit Claise
> has also offered to help if there are any French-speaking authors who would like
> to participate.
> 
> The plan for this work is to do two things: first, to review the documents, and
> secondly, for the participants to have the opportunity to work with Joel or with
> me to improve the quality of their documents.   The goal is specifically for
> non-native english speakers who have documents that the working group
> considers important, but which are felt to need help with english language
> editing.   It is important that the authors _want_ to get help-that they
> recognize that they could use help and that they are comfortable getting that
> help in a small group setting.
> 
> What the meeting will look like is that there will be one or two tables in a
> meeting room; I will be at one table with five authors and a representative
> from the RFC Editor.   Joel will be at a separate table, with the same
> arrangement.   If there aren't enough authors, we may do a single table, as
> we did in Berlin.
> 
> Each of us will have briefly reviewed the five documents prior to the meeting,
> and we expect that the authors will be familiar with each others' documents as
> well.   For thirty minutes per document, we will sit with the author and go
> over the document, offering comments and suggestions and getting feedback
> from the author.   The other authors will follow this. Then we will move on to
> the next author.   Joel will be doing the same thing at the other table.   The
> RFC Editor will be observing and offering advice on request, or if they can't
> resist, but the main goal is to take advantage of the technical editorial
> expertise of the two ADs for this experiment.   At the end of the editing
> session, we will have a half hour session where we talk about what went well, if
> anything, and what went wrong, if anything, and how we might do it better
> next time.
> 
> Neither Joel nor I are experts on teaching english to non-native speakers, so we
> do not claim any specific knowledge other than that we both have a keen
> interest in improving the quality of IETF documents, a fair amount of experience
> in at least trying to do so, and a desire to help our colleagues to accomplish
> their goals.
> 
> Our desired outcome from this meeting is twofold: first, to help the specific
> authors who attend; secondly, to learn how to help authors in general: what
> frustrations they have in writing documents for IETF, what stumbling blocks
> they trip over, and how we can help them.
> 
> What we are asking working group chairs to do is think about whether there
> are documents in their working group that could use this sort of help.   If you
> believe there are, please contact the authors of those documents and ask them
> in a non-pushy way whether they would like to participate in this experiment.
> Please let us know if any of your authors are interested in this.   If you have
> more than one document that you'd like worked on, please tell us which one is
> most important to you.   We will have to do a triage process unless the
> response to this call for participants is tiny, so it's likely that we will only take
> the document you think is more important.   If we get a really good response,
> we won't be able to take documents from every working group that responds;
> please don't take this as a criticism if your document isn't chosen.
> 
> If you think this is a good idea and want to take advantage of it, please contact
> your authors as soon as possible, so that they can make travel plans that allow
> them to get to the venue on Saturday rather than on Sunday.   Please bear in
> mind that the document selection process will take time, and set your authors'
> expectations appropriately.
> 
> We will arrange for authors who wish to attend and who are selected to receive
> invitations, so that they can justify the early arrival to their management if
> necessary.
> 
> Thanks!

---

From: Bill Cerveny <[email-masked]>
Date: Sun, 19 Jan 2014 18:38:03 -0500

[My first rant as a WG chair. I first wrote the rant, then took out maybe 2/3rds of what I wrote :-) ]

Having documents cleaned up grammatically as early as possible is very important and will result in better technical discussions, better (final) documents and a faster document turnaround from submission to publication.

Last year my daughter, a recent college graduate in English, told me she aspired to be a technical writer, at which time I told her, “Gee, how’d you like to get experience reviewing technical documents?” I recruited her to review WG documents primarily from a grammatical, non-technical perspective. She was successful at providing constructive grammatical feedback to WG draft authors.

Having worked with my daughter in in helping her get up to speed in reviewing IETF documents, it seems there are challenges a volunteer reviewer faces:
1) There doesn’t appear to be a clear, concise web page new volunteer reviewers can use as a starting point.
2) How does one determine which documents are fair game for document review?  In theory, any document submitted to the IETF should be open for grammatical review the moment it is submitted, but given limited resources, from a WG perspective, we encourage reviewing WG documents first.
3) How should a reviewer submit proposed changes? There isn’t a consistent IETF recommendation for how to submit review comments/changes (such as format and/or tools) and it seems a consistent recommendation would be useful.
4) There isn’t any mechanism for encouraging (or even rewarding) reviewers who may not be intimately interested in the technical aspects of the documents. I sent my daughter an IETF88 T-shirt, but other than a thanks from the authors and/or the WG chairs, there isn’t much that is done to encourage or reward the reviewers.

At the risk of sounding non-IETFish here (we’re mostly all “volunteers”), in a perfect world, it would make sense for authors to pay a document reviewer to review a document before it is even submitted to the IETF. The time involved with reviewing documents for grammatical correctness can be non-trivial. Certainly, there is an implied financial cost for the time that a volunteer reviewer spends to review a document. If the author is serious about submitting a concise technical document and having a concise technical document published, it would behoove the author to ensure that the document is grammatically correct before it is submitted to engineers for technical scrutiny. In this perfect world, there might be some sort of central list of people willing to review documents, although at a larger organization, it should be possible for the author to ask someone at the organization to review the document.

Bill Cerveny

---

From: Michael Richardson <[email-masked]>
Date: Sun, 19 Jan 2014 18:53:51 -0500

Bill Cerveny <[email-masked]> wrote:
    > 2) How does one determine which documents are fair game for document
    > review?  In theory, any document submitted to the IETF should be open
    > for grammatical review the moment it is submitted, but given limited
    > resources, from a WG perspective, we encourage reviewing WG documents
    > first.

I think that this is partially just a matter of some interesting views (which
might already exist) on the datatracker... I think that the better question
is, how early is it worth while?   My opinion is that the first review is
somewhere around WG adoption stage, and I'd like to say *before*, but I think
that this costs too much.

    > 4) There isn’t any mechanism for encouraging (or even rewarding)
    > reviewers who may not be intimately interested in the technical aspects
    > of the documents. I sent my daughter an IETF88 T-shirt, but other than
    > a thanks from the authors and/or the WG chairs, there isn’t much that
    > is done to encourage or reward the reviewers.

I just want to leave this part here.
We have some significant incentive issues to work out.

---

From: Ted Lemon <[email-masked]>
Date: Sun, 19 Jan 2014 19:05:07 -0500

Just to clarify, the point of the language editing session is not to help non-native speakers to express themselves better in english through the process of reviewing and editing their documents, not to correct trivial grammatical errors.   The point of having a technical reviewer do this work is that we are more likely to understand what is intended, and therefore be able to suggest better ways of expressing it.

You are absolutely right that the other sort of work is also useful, and might well be able to be accomplished by reviewers who are interested in honing their tech writing chops.   It is worth noting that the RFC Editor function at the IETF is staffed by people who are in fact already quite good at that.   But as you say, doing the editing earlier in the process is definitely helpful, and the RFC editor can't help very much with that.

To answer Michael's question, it is helpful to do these edits early in the process because it can make the document easier to review.   To answer your question, it is _always_ in scope to review an internet draft.   However, it's up to the authors to read your review and update the draft, and there is no guarantee that they will do so, so it can't hurt to ask.

Any document that's in a call for adoption or working group last call would be a good document to do this work on.   Also, any document that covers a topic you find interesting.   There's never a guarantee that your work will be useful when you review a document, because documents don't always survive working group last call or IETF last call.   So you have to be willing to risk a little to contribute to the process of improving documents.

---

From: Bill Cerveny <[email-masked]>
Date: Sun, 19 Jan 2014 20:00:19 -0500

Ted,

Thanks for the clarifications.There was a sentence in your initial e-mail about ADs offering "technical editoral expertise".  I'm curious myself; it would seem any technical author would find this advice useful, as ADs must see/review an insane number of documents. It would be interesting to have ADs (or even previous ADs) offer their technical perspective on what they look for in documents and what common problems that they see in documents they review.

Thanks,

Bill

---

From: "Murphy, Sandra" <[email-masked]>
Date: Mon, 20 Jan 2014 15:20:22 +0000

Speaking of editing:

>Just to clarify, the point of the language editing session is not to help non-native speakers to express themselves >better in english through the process of reviewing and editing their documents, not to correct trivial grammatical >errors.

This is unclear.  I'm guessing that one of those "not"s is not supposed to be "not".  :-)

--Sandy

________________________________________
From: WGChairs [[email-masked]] on behalf of Ted Lemon [[email-masked]]
Sent: Sunday, January 19, 2014 7:05 PM
To: Bill Cerveny
Cc: [email-masked] Chairs; Heather Flanagan (RFC Series Editor)
Subject: Re: Document language editing session in London

---

From: Paul Kyzivat <[email-masked]>
Date: Mon, 20 Jan 2014 10:26:19 -0500

I have a very different view of this from Bill.

IMO, especially early in the process, what is important is to discuss 
the *concepts* in a draft, not the language usage. This is true whether 
the author is just a grammatically inept native English speaker/writer, 
or if the author doesn't have English as his native language.

I find that documents written by many non-native English writers have 
usage that is "unusual" for natives, but in general it is still 
perfectly understandable. I find it easier to just "let it be" until the 
document is quite mature and the discussion of basics is over and it is 
time for polishing.

Discussing language style and grammar in the midst of technical 
discussions is very distracting.

	Thanks,
	Paul

---

From: Ted Lemon <[email-masked]>
Date: Mon, 20 Jan 2014 13:48:51 -0500

> This is unclear.  I'm guessing that one of those "not"s is not supposed to be "not".  :-)

Oops.   You are correct.   :)

---

From: Ted Lemon <[email-masked]>
Date: Mon, 20 Jan 2014 13:55:46 -0500

On Jan 19, 2014, at 8:00 PM, Bill Cerveny <[email-masked]> wrote:
> It would be interesting to have ADs (or even previous ADs) offer their technical perspective on what they look for in documents and what common problems that they see in documents they review.

Different ADs look for different things.   We're supposed to consider process as well as content, and there's plenty of process to consider.   We also have debates about how to look at content, not only with each other but with document authors.   I can say for my part that I don't always find myself winning these debates—sometimes my reaction to what the authors did misses the author's intentions, and once that's clear my objection becomes clearly invalid.

The best ways to become exposed to these discussions are, in no particular order, to be a document shepherd, to be a working group chair, and to be a document author.

---

From: "DRAGE, Keith (Keith)" <[email-masked]>
Date: Tue, 21 Jan 2014 02:25:51 +0000

Conversely, at the stage of IESG approval the Ads should not be worrying with this at all.

Given that the document is meant to be complete technically before WGLC, at that point we should be able yo ascertain that:
-	the document is clearly written
-	that all requirements are clear
The WGLC will obviously polish this, but it is really the responsibility of the WG chair to ensure this.

Keith 

> From: WGChairs [mailto:[email-masked]] On Behalf 
> Of Paul Kyzivat
> Sent: 20 January 2014 15:26
> To: [email-masked]
> IMO, especially early in the process, what is important is to 
> discuss the *concepts* in a draft, not the language usage. 
> This is true whether the author is just a grammatically inept 
> native English speaker/writer, or if the author doesn't have 
> English as his native language.
> 
> I find that documents written by many non-native English 
> writers have usage that is "unusual" for natives, but in 
> general it is still perfectly understandable. I find it 
> easier to just "let it be" until the document is quite mature 
> and the discussion of basics is over and it is time for polishing.
> 
> Discussing language style and grammar in the midst of 
> technical discussions is very distracting.
> 
> 	Thanks,
> 	Paul
> 
> > Having documents cleaned up grammatically as early as 
> possible is very important and will result in better 
> technical discussions, better (final) documents and a faster 
> document turnaround from submission to publication.
> >
> > Last year my daughter, a recent college graduate in 
> English, told me she aspired to be a technical writer, at 
> which time I told her, "Gee, how'd you like to get experience 
> reviewing technical documents?" I recruited her to review WG 
> documents primarily from a grammatical, non-technical 
> perspective. She was successful at providing constructive 
> grammatical feedback to WG draft authors.
> >
> > Having worked with my daughter in in helping her get up to 
> speed in reviewing IETF documents, it seems there are 
> challenges a volunteer reviewer faces:
> > 1) There doesn't appear to be a clear, concise web page new 
> volunteer reviewers can use as a starting point.
> > 2) How does one determine which documents are fair game for 
> document review?  In theory, any document submitted to the 
> IETF should be open for grammatical review the moment it is 
> submitted, but given limited resources, from a WG 
> perspective, we encourage reviewing WG documents first.
> > 3) How should a reviewer submit proposed changes? There 
> isn't a consistent IETF recommendation for how to submit 
> review comments/changes (such as format and/or tools) and it 
> seems a consistent recommendation would be useful.
> > 4) There isn't any mechanism for encouraging (or even 
> rewarding) reviewers who may not be intimately interested in 
> the technical aspects of the documents. I sent my daughter an 
> IETF88 T-shirt, but other than a thanks from the authors 
> and/or the WG chairs, there isn't much that is done to 
> encourage or reward the reviewers.
> >
> > At the risk of sounding non-IETFish here (we're mostly all 
> "volunteers"), in a perfect world, it would make sense for 
> authors to pay a document reviewer to review a document 
> before it is even submitted to the IETF. The time involved 
> with reviewing documents for grammatical correctness can be 
> non-trivial. Certainly, there is an implied financial cost 
> for the time that a volunteer reviewer spends to review a 
> document. If the author is serious about submitting a concise 
> technical document and having a concise technical document 
> published, it would behoove the author to ensure that the 
> document is grammatically correct before it is submitted to 
> engineers for technical scrutiny. In this perfect world, 
> there might be some sort of central list of people willing to 
> review documents, although at a larger organization, it 
> should be possible for the author to ask someone at the 
> organization to review the document.
> >
> > Bill Cerveny
> >
> >> As a non-native English speaker, I agree that this is a 
> good practice to improve the quality of IETF I-Ds.
> >>
> >> I also share the opinion of Thomas that more volunteers 
> should be called to help the whole community. Probably the 
> similar practice could be conducted in a more "distributed" 
> way, e.g., in WG level, led by WG co-chairs.
> >>
> >> Anyway, I will plan to submit I-D to this session in London, learn 
> >> something important, then talk to my group, especially as a 
> >> non-native English WG co-chair. :-)
> >>
> >> Thanks.
> >>
> >> -Ning
> >>
> >>> From: WGChairs [mailto:[email-masked]] On 
> Behalf Of Ted 
> >>> Lemon
> >>> has also offered to help if there are any French-speaking authors 
> >>> who would like to participate.
> >>>
> >>> The plan for this work is to do two things: first, to review the 
> >>> documents, and secondly, for the participants to have the 
> opportunity to work with Joel or with
> >>> non-native english speakers who have documents that the working 
> >>> group considers important, but which are felt to need 
> help with english language
> >>> recognize that they could use help and that they are comfortable 
> >>> getting that help in a small group setting.
> >>>
> >>> What the meeting will look like is that there will be one or two 
> >>> tables in a meeting room; I will be at one table with 
> five authors and a representative
> >>> Each of us will have briefly reviewed the five documents prior to 
> >>> the meeting, and we expect that the authors will be 
> familiar with each others' documents as
> >>> RFC Editor will be observing and offering advice on 
> request, or if 
> >>> they can't resist, but the main goal is to take advantage 
> of the technical editorial
> >>> session, we will have a half hour session where we talk 
> about what 
> >>> went well, if anything, and what went wrong, if anything, 
> and how we 
> >>> might do it better next time.
> >>>
> >>> Neither Joel nor I are experts on teaching english to non-native 
> >>> speakers, so we do not claim any specific knowledge other 
> than that 
> >>> we both have a keen interest in improving the quality of IETF 
> >>> documents, a fair amount of experience in at least trying 
> to do so, 
> >>> and a desire to help our colleagues to accomplish their goals.
> >>>
> >>> Our desired outcome from this meeting is twofold: first, 
> to help the 
> >>> specific authors who attend; secondly, to learn how to 
> help authors 
> >>> in general: what frustrations they have in writing documents for 
> >>> IETF, what stumbling blocks they trip over, and how we 
> can help them.
> >>>
> >>> believe there are, please contact the authors of those 
> documents and 
> >>> ask them in a non-pushy way whether they would like to 
> participate in this experiment.
> >>> we won't be able to take documents from every working group that 
> >>> responds; please don't take this as a criticism if your 
> document isn't chosen.
> >>>
> >>> If you think this is a good idea and want to take 
> advantage of it, 
> >>> please contact your authors as soon as possible, so that 
> they can make travel plans that allow
> >>> We will arrange for authors who wish to attend and who 
> are selected 
> >>> to receive invitations, so that they can justify the 
> early arrival 
> >>> to their management if necessary.
> >>>
> >>> Thanks!
> >>
> >
> >
> 
>

---

From: Ted Lemon <[email-masked]>
Date: Mon, 20 Jan 2014 22:15:10 -0500

On Jan 20, 2014, at 10:26 AM, Paul Kyzivat <[email-masked]> wrote:
> I find that documents written by many non-native English writers have usage that is "unusual" for natives, but in general it is still perfectly understandable. I find it easier to just "let it be" until the document is quite mature and the discussion of basics is over and it is time for polishing.

You are probably much smarter than me.   For whatever reason, I find a lot of documents difficult to follow, even after IETF last call.  Hence the motivation to try to help improve them.

---

From: "Pascal Thubert (pthubert)" <[email-masked]>
Date: Tue, 21 Jan 2014 06:43:02 +0000

As a non-Native chair, Keith, I'm unclear how I can accomplish that. 
Maybe the WG could have a more official position for a secretary who would have to be fluent in English?
Would that be a slippery slope?

Cheers,

Pascal

> From: WGChairs [mailto:[email-masked]] On Behalf Of DRAGE,
> Keith (Keith)
> Sent: mardi 21 janvier 2014 03:26
> To: Paul Kyzivat; [email-masked]
> Subject: RE: Document language editing session in London
> 
> Given that the document is meant to be complete technically before WGLC, at
> that point we should be able yo ascertain that:
> > From: WGChairs [mailto:[email-masked]] On Behalf Of Paul
> > Kyzivat
> > the *concepts* in a draft, not the language usage.
> > This is true whether the author is just a grammatically inept native
> > English speaker/writer, or if the author doesn't have English as his
> > native language.
> >
> > perfectly understandable. I find it easier to just "let it be" until
> > the document is quite mature and the discussion of basics is over and
> > it is time for polishing.
> >
> > possible is very important and will result in better technical
> > discussions, better (final) documents and a faster document turnaround
> > from submission to publication.
> > >
> > English, told me she aspired to be a technical writer, at which time I
> > told her, "Gee, how'd you like to get experience reviewing technical
> > documents?" I recruited her to review WG documents primarily from a
> > grammatical, non-technical perspective. She was successful at
> > providing constructive grammatical feedback to WG draft authors.
> > >
> > speed in reviewing IETF documents, it seems there are challenges a
> > volunteer reviewer faces:
> > document review?  In theory, any document submitted to the IETF should
> > be open for grammatical review the moment it is submitted, but given
> > limited resources, from a WG perspective, we encourage reviewing WG
> > documents first.
> > isn't a consistent IETF recommendation for how to submit review
> > comments/changes (such as format and/or tools) and it seems a
> > consistent recommendation would be useful.
> > rewarding) reviewers who may not be intimately interested in the
> > technical aspects of the documents. I sent my daughter an
> > IETF88 T-shirt, but other than a thanks from the authors and/or the WG
> > chairs, there isn't much that is done to encourage or reward the
> > reviewers.
> > >
> > "volunteers"), in a perfect world, it would make sense for authors to
> > pay a document reviewer to review a document before it is even
> > submitted to the IETF. The time involved with reviewing documents for
> > grammatical correctness can be non-trivial. Certainly, there is an
> > implied financial cost for the time that a volunteer reviewer spends
> > to review a document. If the author is serious about submitting a
> > concise technical document and having a concise technical document
> > published, it would behoove the author to ensure that the document is
> > grammatically correct before it is submitted to engineers for
> > technical scrutiny. In this perfect world, there might be some sort of
> > central list of people willing to review documents, although at a
> > larger organization, it should be possible for the author to ask
> > someone at the organization to review the document.
> > >
> > > Bill Cerveny
> > >
> > should be called to help the whole community. Probably the similar
> > practice could be conducted in a more "distributed"

---

From: Yoav Nir <[email-masked]>
Date: Tue, 21 Jan 2014 07:03:21 +0000

> Would that be a slippery slope?

Sure would. Define "fluent".

Do we need to be able to construct sentences like these to be considered fluent?

"I would have been going to have had the document have some more language review before the next meeting, but then I would have had to have the authors not have time to polish the technical aspects sufficiently."

Not bad for someone whose native language does not have perfect tenses, right?

Seriously, though, most of us are fluent enough to produce a clear technical document, and to know one when we see one. Those who don't can and should seek help. There are certain mistakes that we are more likely to make or overlook. Improper (for English) use of commas is one. Mishandling of tenses is another. Splitting infinitives. But those are not harmful to understanding, and the RFC editor can and does fix them. 

Yoav

---

From: joel jaeggli <[email-masked]>
Date: Mon, 20 Jan 2014 23:16:29 -0800

> Would that be a slippery slope?

I very much do not want to come out of this series of experiments with
more requirements.

---

From: "DRAGE, Keith (Keith)" <[email-masked]>
Date: Tue, 21 Jan 2014 08:28:06 +0000

I'm not saying that a chair has to do it, only ensure that it is done.

Given that we have non-native ADs it is certainly more ridiculous to expect them to do it.

I'd also indicate that in many respects requirement writing is not good english. We are not looking for creating a variety of style, good prose or anything like that. We are looking for absolute clarity in the specification, such that there can be no misinterpretation. As such anyone who can learn a variety of programming languages should not find this substantially more difficult. 

Keith

> From: Pascal Thubert (pthubert) [mailto:[email-masked]] 
> Sent: 21 January 2014 06:43
> To: DRAGE, Keith (Keith); Paul Kyzivat; [email-masked]
> Maybe the WG could have a more official position for a 
> secretary who would have to be fluent in English?
> Of DRAGE, 
> > Given that the document is meant to be complete technically before 
> > WGLC, at that point we should be able yo ascertain that:
> > The WGLC will obviously polish this, but it is really the 
> > responsibility of the WG chair to ensure this.
> > 
> > Keith
> > 
> Behalf Of Paul 
> > > I find that documents written by many non-native English writers 
> > > have usage that is "unusual" for natives, but in general 
> it is still 
> > > the document is quite mature and the discussion of basics is over 
> > > and it is time for polishing.
> > >
> > > discussions, better (final) documents and a faster document 
> > > turnaround from submission to publication.
> > > >
> which time 
> > > I told her, "Gee, how'd you like to get experience reviewing 
> > > technical documents?" I recruited her to review WG documents 
> > > primarily from a grammatical, non-technical perspective. She was 
> > > successful at providing constructive grammatical feedback 
> to WG draft authors.
> > > >
> > > document review?  In theory, any document submitted to the IETF 
> > > should be open for grammatical review the moment it is submitted, 
> > > but given limited resources, from a WG perspective, we encourage 
> > > reviewing WG documents first.
> and/or the 
> > > WG chairs, there isn't much that is done to encourage or 
> reward the 
> > > reviewers.
> > > >
> > > "volunteers"), in a perfect world, it would make sense 
> for authors 
> > > to pay a document reviewer to review a document before it is even 
> > > submitted to the IETF. The time involved with reviewing documents 
> > > for grammatical correctness can be non-trivial. 
> Certainly, there is 
> > > an implied financial cost for the time that a volunteer reviewer 
> > > spends to review a document. If the author is serious about 
> > > submitting a concise technical document and having a concise 
> > > technical document published, it would behoove the author 
> to ensure 
> > > that the document is grammatically correct before it is 
> submitted to 
> there might 
> > > be some sort of central list of people willing to review 
> documents, 
> > > although at a larger organization, it should be possible for the 
> > > author to ask someone at the organization to review the document.
> > > >
> > > > Bill Cerveny
> > > >
> > > >> Anyway, I will plan to submit I-D to this session in London, 
> > > >> learn something important, then talk to my group, 
> especially as a 
> > > >>> has also offered to help if there are any French-speaking 
> > > >>> authors who would like to participate.
> > > >>>
> > > >>> Each of us will have briefly reviewed the five 
> documents prior 
> > > >>> to the meeting, and we expect that the authors will be

---

From: "Scharf, Michael (Michael)" <[email-masked]>
Date: Tue, 21 Jan 2014 10:45:45 +0000

> From: WGChairs [mailto:[email-masked]] On Behalf Of Pascal
> Thubert (pthubert)
> Sent: Tuesday, January 21, 2014 7:43 AM

As a non-native speaker, I am not sure if we could indeed find native speakers inside the WG who would be really eager to do this kind of work.

My observation is that usually some native speakers are willing to help out (e.g., during WGLC), but on a voluntary basis only, i.e., if they happen to have spare cycles.

Michael

> > Conversely, at the stage of IESG approval the Ads should not be
> worrying with
> > this at all.
> >
> WGLC, at
> discuss
> native
> have
> > > > [My first rant as a WG chair. I first wrote the rant, then took
> out
> > > > maybe 2/3rds of what I wrote :-) ]
> > > >
> should
> for
> learn

---

From: Thomas Narten <[email-masked]>
Date: Tue, 21 Jan 2014 10:53:01 -0500

My larger point about all this is:

1) Per my first message, the ADs shouldn't be sitting down with
authors to teach them how to write. It doesn't scale and I have a hard
time seeing it address the real problem in a meaningful way. If that
were part of a larger plan, maybe it would make sense, but I don't
recall discussion of a larger plan.

2) The problem of poor writing is big and hard. If we were seriously
interested in fixing it, my usual recommendation is to create a design
team of sorts (formal or informal) that looks at the bigger picture
and thinks through it in more detail - and then has the output of the
group reviewed by others. I.e, having a clear problem statement, clear
goals, and an execution strategy, etc. And an important thing here is
to have a real plan that folk think might actually help the overall
problem. Otherwise, the community ends up making poor use of our
(limited) cycles.

For example, what probably has to happen with any document that
suffers from poor writing is pair the existing authors with a new
author (that has the required skills). But that raises authorship
issues... But the idea that you can do a one-off review to fix writing
issues and expecting the existing authors to continue to edit the
document without continuing to make repeat mistakes seems naive.

For me, I absolutely hate reviewing other peoples documents for basic
english stuff. It takes 3 times as long to type up such a review as it
does to just make the editing changes in place. Not a great use of
time, especially if it doesn't fix the problem going forward.

Thomas

---

From: Paul Kyzivat <[email-masked]>
Date: Tue, 21 Jan 2014 10:55:45 -0500

Well said!
+1

---

From: Jeffrey Haas <[email-masked]>
Date: Tue, 21 Jan 2014 13:57:57 -0500

On Sun, Jan 19, 2014 at 06:53:51PM -0500, Michael Richardson wrote:
>     > 4) There isn???t any mechanism for encouraging (or even rewarding)
>     > a thanks from the authors and/or the WG chairs, there isn???t much that

I had sent a feature request to the IAOC folk to implement a "karma" system
in our tools.  

While certainly not as good as being taken out to dinner, it's something.

-- Jeff

---

From: Bert Greevenbosch <[email-masked]>
Date: Wed, 22 Jan 2014 00:46:35 +0000

> From: WGChairs [mailto:[email-masked]] On Behalf Of Scharf,
> Michael (Michael)
> Sent: 21 January 2014 18:46
> To: Pascal Thubert (pthubert); DRAGE, Keith (Keith); Paul Kyzivat;
> [email-masked]
> As a non-native speaker, I am not sure if we could indeed find native
> speakers inside the WG who would be really eager to do this kind of
> work.
> 
> My observation is that usually some native speakers are willing to help
> out (e.g., during WGLC), but on a voluntary basis only, i.e., if they
> happen to have spare cycles.

Indeed, I agree this kind of work should be done on a voluntary basis.

But I certainly see value in it. So I think it is a very good initiative from Ted and Joel to initiate such a language session.

One could also consider to create a list of volunteers generally willing to help on reviewing the language in the documents. In that way such work is not restricted to a Saturday session, and it also gives volunteers the freedom to help when it is convenient to them. It may also lead to better quality documents before the meeting, as the documents could be updated before the submission deadline.

Although not a native speaker, I would be happy to be on that list. :-)

> > > > IETF88 T-shirt, but other than a thanks from the authors and/or
> the
> > WG
> authors
> > to
> document
> > is
> > > > technical scrutiny. In this perfect world, there might be some
> sort
> > of
> similar
> > > > >>> Each of us will have briefly reviewed the five documents
> prior
> > to

---

From: "Fred Baker (fred)" <[email-masked]>
Date: Wed, 22 Jan 2014 01:45:41 +0000

> 1) There doesn’t appear to be a clear, concise web page new volunteer reviewers can use as a starting point.

This is probably a question for your daughter. What would they want on the web page? For example, the RFC Editor has a style guide; I presume thats of interest. I could imagine a "what would you hope to find in an RFC" discussion, but you know as well as I that the topic is all over the map. 

> 2) How does one determine which documents are fair game for document review?  In theory, any document submitted to the IETF should be open for grammatical review the moment it is submitted, but giv…

Yes. draft-ietf-*. There is room for individual submissions as well, but they come and go.

> 3) How should a reviewer submit proposed changes? There isn’t a consistent IETF recommendation for how to submit review comments/changes (such as format and/or tools) and it seems a consistent reco…

Well, I don't have an RFC to point you to. I can comment on AUTH48 guidelines. 

*** OLD ***
A really strange bit of text this is
*** NEW ***
This is a really strange bit of text
***

I might add that, since this is presumably a friendly amendment to some well-meaning person's document, that there be a note to say *why* the new text is suggested.

> 4) There isn’t any mechanism for encouraging (or even rewarding) reviewers who may not be intimately interested in the technical aspects of the documents. I sent my daughter an IETF88 T-shirt, but…

For you and me, it's part of what we do.

"That depends". If they're willing to do it and good at it, I could imagine them getting paid. There's a service in London, a bit of spam told me once, that will take a document formatted in Microsoft Word, turn it into English, and send it back. Since this is done with "Track Changes", the author has the option of wondering whether the suggested edits are in fact in keeping with the document. They do it for a set price scaled by the document size. I haven't actually used the service, but I have thought about it.

If your daughter is coming to the IETF meeting, I'd buy her a beverage of her choice...

> At the risk of sounding non-IETFish here (we’re mostly all “volunteers”), in a perfect world, it would make sense for authors to pay a document reviewer to review a document before it is even submitted to the IETF.

If the authors are paying, so be it. The ESL co-authors I have worked with seem to have the idea that an english-speaking co-author solves that problem.

See comment above about individual submissions. I have seen a lot of documents that are well described as having a lot of blanks that the author plans to fill in, or which are going to need a lot of work before they even resemble an output. It would be nice to have perfect input, but ... 

The place I'd suggest that is the transition from an individual submission to a working group document, or just before working group last call.

> The time involved with reviewing documents for grammatical correctness can be non-trivial. Certainly, there is an implied financial cost for the time that a volunteer reviewer spends to review a document. If the author is serious about submitting a concise technical document and having a concise technical document published, it would behoove the author to ensure that the document is grammatically correct before it is submitted to engineers for technical scrutiny. In this perfect world, there might be some sort of central list of people willing to review documents, although at a larger organization, it should be possible for the author to ask someone at the organization to review the document.

No complaint about the perfect world, but - to be very blunt and honest, I work in a global company, and the IETF is a global bunch of engineers. "Accents" and their written counterparts are part of life. I'm far more interested in the content being technically astute than written in perfect English. 

>>> invitations, so that they can justify the early arrival to their management if

------------------------------------------------------
8 issues in virtual infrastructure
http://dcrocker.net/#fallacies

---

From: Loa Andersson <[email-masked]>
Date: Wed, 22 Jan 2014 13:22:16 +0800

Thomas,

I think this is a two way process, both ADs and authors learn.
Why block or discourage ADs form taking part if they see it useful?

You are right, having ADs as the means to make this happen does not
scale.

/Loa

-- 

Loa Andersson                        email: [email-masked]
Senior MPLS Expert                          [email-masked]
Huawei Technologies (consultant)     phone: +46 739 81 21 64

---

From: Bill Cerveny <[email-masked]>
Date: Sun, 26 Jan 2014 11:38:48 -0500

As Fred suggested, I pinged my daughter (a recent English grad who has reviewed some IETF Internet-drafts) on this topic ... below is her response ...

<begin response>
1) There doesn’t appear to be a clear, concise web page new volunteer reviewers can use as a starting point.
	• Agreed. While the 'Info for Newcomers' tab is pretty straightforward, and I found a lot of great resources on there, it might be more helpful as it's own page with it's own tabs. Perhaps something a bit more all-inclusive than having to hop around the website to connect dots, such as with finding WG groups, or stumbling upon the RFC Style Guide (which, by the way, I found tremendously helpful). 

2) How does one determine which documents are fair game for document review?  In theory, any document submitted to the IETF should be open for grammatical review the moment it is submitted, but given limited resources, from a WG perspective, we encourage reviewing WG documents first.
	• It's hard for me to comment on this, because the WG I subscribed to never got back to me. There was definitely confusion on my end in regards to what I should focus on, and as a new comer I wasn't sure if all documents were within my right to edit... if that makes any sense.

3) How should a reviewer submit proposed changes? There isn’t a consistent IETF recommendation for how to submit review comments/changes (such as format and/or tools) and it seems a consistent recommendation would be useful.
	• This was, by far, the most difficult part of starting up as a new comer. I tried editor after editor, which consequently weren't compatible with my laptop, and finally settled on XML Editor. My end result has been opening the drafts through my XML Editor and transcribing mistakes and corrections into Google Word Docs, corresponding line numbers. It was hard for me to gage what my corrections should look like without samples.

4) There isn’t any mechanism for encouraging (or even rewarding) reviewers who may not be intimately interested in the technical aspects of the documents. I sent my daughter an IETF88 T-shirt, but other than a thanks from the authors and/or the WG chairs, there isn’t much that is done to encourage or reward the reviewers.
	• This is an interesting point. I see it from two very different angles. The first being that I don't expect to be paid for my contributions. I love editing, it's a passion of mine, and I like helping because I get to fuse my interest in the internet and IT with my enjoyment of writing. Receiving 'Thank-Yous' from people who appreciated my commentary was above and beyond what I expected, and I treasured it because I felt like my input was valued and helpful. As an editor, that is all you can hope for. 
          On the other hand, there is definitely merit in paying someone to edit submissions. It would certainly heighten the incentive to review documents in a more timely manner, lengthen the input and detail, and enhance the quality. 

Also, grammatically, you used "in" twice in the third paragraph (directly above your bullet points).
<end response>

Regards,

Bill Cerveny