Subject: [Roll] English usage in I-D's

From: "Colin O'Flynn" <[email-masked]>
Date: Thu, 19 Aug 2010 15:35:42 +0100

Hello,

I finally got time to catching up on some of the latest I-D's. I'm a little
taken back by the complexity of English used in the drafts, especially
references to more academic things and just all-around inconsistency. 

People reading these will likely be engineers needing to implement the
standards. I pain to see how someone with English as a second language who
has been away from the academic side of things for a while will do.

I know RPL has gone to the IETF so it's too late to post things here, but
thought I'd put them up here first anyway for comments. Maybe I'm just
missing something.

As a few examples:

#1) Trickle from mailing list discussion

> For the WG, the misunderstanding was coming from the the use of different 

> notation. In some countries we use [a,b[ instead:

> But that's OK let's use the [a,b) notation.

There is even a chance to confuse people IN the field! Why not either define
what is meant by writing it out, or use something like 'a <= x < b'? I see a
note that a 'natural langauge' description will be added which makes sense
hopefully...

#2) Trickle + RPL Together (from section 8.3, RPL)

> Note that this list is not exhaustive, and an implementation MAY

> consider other messages or events to be inconsistencies.

My implementation could consider the "main oscillator oscillating" an
inconsistency by that wording, and just transmit DIO packets as long as it
wanted couldn't it, and be 100% to spec? There is something to be said for
not trying to make the specification too flexible I think.

In all seriousness though shouldn't this section have better linkage?
Section 5 of the trickle draft says what the protocol specification needs to
specify. The Imin/Imax/k are specified well in section 8.3.1. However the
definition of a "consistent" transmission is semi-hidden in the paragraph:

>       A DIO from a sender with a lesser DAGRank

>       that causes no changes to the recipient's parent set, preferred

>       parent, or Rank SHOULD be considered consistent with respect to the

>       Trickle timer.

Am I just stupid, or would it be better if that section (8.3) was reworded
such that it explicitly states what a "consistent transmission" and
"inconsistent transmission" is, and possibly combined with section 8.3.1. By
this I mean consider someone who sees in the Trickle draft that RPL should
specify those six items, then wants to quickly find them in the RPL draft.
They would find Imin/Imax/k no problem as they are well defined in an
appropriately titled section. The only chance of finding the other three is
if you looked above section 8.3.1, or searched the document for the word
'Trickle'.

#3) Option Length Definitions

Let's look at all the different wordings for 'option length':

>Option Length:  8-bit unsigned integer, representing the length in

>        octets of the option, not including the Option Type and Length

>         fields.

>Option Length:  For N (N > 1) octets of padding, the Option Length

>         field contains the value N-2.

>Option Length:  The Option Length field contains the length in octets

>         of the Metric Data.

>Option Length:  Variable, length of the option in octets excluding

>         the Type and Length fields.  Note that this length is expressed

>         in units of single-octets, unlike in IPv6 ND.

>Option Length:  14

>Option Length:  Variable, length of the option in octets excluding

>         the Type and Length fields.

>Option Length:  Variable, depending on whether or not Parent Address

>         is present.

>Option Length:  19

>Option Length:  30.  Note that this length is expressed in units of

>         single-octets, unlike in IPv6 ND.

>Option Length:  4

I count 10 definitions of option length. The only ones that are consistent
are the 13/19/4 types, every other definition uses a different wording. 

#4) Use of too many Words

The purpose of English is to communicate clearly. Adding more words than
needed detracts from that purpose. You write to be understood by the reader,
not to feel good about what you are writing. Consider the following
beauties:

4.1 - OF (from section 3.7, RPL)

>       The Objective Function itself is decoupled from the routing metrics
>       and constraints used by RPL.  Indeed, whereas the OF dictates rules
>       such as DODAG parents selection, load balancing and so on, the set
of
>       metrics and/or constraints used, and thus determine the preferred
>       path, are based on the information carried within the DAG container
>       option in DIO messages.

Amazingly there is two sentences in there; the first one makes sense but is
a little complicated, the second one has five commas and seems to be written
by two different people about half-way through.

4.2 - Loop Avoidance (from section 3.8, RPL)      

>       "rank-based datapath validation mechanisms"

Despite the fact this section is a repeat of elsewhere (see #5), this is a
great example of what I mean. The first phrase is a less clear way of saying
either "validating rank" or even better "checking packets are moving in the
intended direction". Of course a "rank-based datapath validation mechanism"
sounds like more of an achievement than either of those two.

4.3 - Greediness (from section 3.8.1, RPL)

All of section 3.8.1/3.8.1.1 seems unnecessary. RPL doesn't allow greediness
- case closed. If you want to learn about greediness in general the RPL
draft isn't the location. 

4.4 - Introduction (section 1, 1.2, RPL)

>       Examples of such objectives include
>       minimizing energy, minimizing latency, or satisfying constraints

Of course, 'satisfying constraints'. Wait, isn't minimizing energy and
minimizing latency also satisfying a constraint?

>   RPL
>   is designed to be able to operate over a variety of different link
>   layers, including ones that are constrained, potentially lossy, or
>   typically utilized in conjunction with highly constrained host or
>   router devices, such as but not limited to, low power wireless or PLC
>   (Power Line Communication) technologies.

Was this a contest to write the words "different link layers" in as many
words as possible? 

#5) Sections that repeat the same information (RPL)

This is mostly a problem in section 3. Lots of information is repeated in
different locations, which just makes it longer and more confusing.

Consider section 3.8 and section 3.3.7. They are both in the overview and
deal with loops, and basically say the same thing. There's some more loop
stuff later even in section 3.8.2, but it's at least a tiny bit different! 

Throughout most of the introduction there is similar things. Section 3.7 has
two paragraphs about the objective function, but then there is also a
separate paragraph in section 3.3.1 about the objective function. Further it
seems random if 'Objective Function', 'OF', 'Objective Function (OF)', or
'objective function' is used in the whole document. 

There's plenty more but I haven't gone through everything. My comments here
are purely on how the draft is written, nothing technical. I'm not sure how
the IETF works but hopefully we could clean this up a lot without affecting
LC, since it's not actually changing any packet formats or logic. 

Regards,

  -Colin O'Flynn

---

From: Philip Levis <[email-masked]>
Date: Thu, 19 Aug 2010 09:58:25 -0700

On Aug 19, 2010, at 7:35 AM, Colin O'Flynn wrote:

> Hello,
>  
> I finally got time to catching up on some of the latest I-D's. I'm a little taken back by the complexity of English used in the drafts, especially references to more academic things and just all-around inconsistency.
>  
> People reading these will likely be engineers needing to implement the standards. I pain to see how someone with English as a second language who has been away from the academic side of things for a while will do.
>  
> I know RPL has gone to the IETF so it’s too late to post things here, but thought I’d put them up here first anyway for comments. Maybe I’m just missing something.
>  
> As a few examples:
>  
> There is even a chance to confuse people IN the field! Why not either define what is meant by writing it out, or use something like 'a <= x < b'? I see a note that a 'natural langauge' description will be added which makes sense hopefully...

Yes, that description was added. 

"When an interval begins, Trickle resets c to 0 and sets t to a
random point in the interval, taken from the range [I/2, I), that is,
values greater than or equal to I/2 and less than I. The interval ends
at I."

> My implementation could consider the "main oscillator oscillating" an inconsistency by that wording, and just transmit DIO packets as long as it wanted couldn't it, and be 100% to spec? There is something to be said for not trying to make the specification too flexible I think.
>  
> In all seriousness though shouldn't this section have better linkage? Section 5 of the trickle draft says what the protocol specification needs to specify. The Imin/Imax/k are specified well in section 8.3.1. However the definition of a “consistent” transmission is semi-hidden in the paragraph:
>  
> Am I just stupid, or would it be better if that section (8.3) was reworded such that it explicitly states what a “consistent transmission” and “inconsistent transmission” is, and possibly combined with section 8.3.1. By this I mean consider someone who sees in the Trickle draft that RPL should specify those six items, then wants to quickly find them in the RPL draft. They would find Imin/Imax/k no problem as they are well defined in an appropriately titled section. The only chance of finding the other three is if you looked above section 8.3.1, or searched the document for the word ‘Trickle’.

This section was very carefully worded. Please note that the definition of what constitutes a consistent transmission is an optimization method: it leads to suppression, reducing communication and energy expenditure. If a node does not suppress (e.g., k=infinity, defines nothing as consistent), then it simply transmits every interval. In contrast, the definition of what is *inconsistent* is critical for correctness. Hence the inconsistencies being defined as MUSTs.

> Let’s look at all the different wordings for ‘option length’:
>  
> I count 10 definitions of option length. The only ones that are consistent are the 13/19/4 types, every other definition uses a different wording.
>  
> The purpose of English is to communicate clearly. Adding more words than needed detracts from that purpose. You write to be understood by the reader, not to feel good about what you are writing. Consider the following beauties:
>  
> 4.1 – OF (from section 3.7, RPL)
>  
> >       such as DODAG parents selection, load balancing and so on, the set of
> Amazingly there is two sentences in there; the first one makes sense but is a little complicated, the second one has five commas and seems to be written by two different people about half-way through.

Colin -- we have had this discussion on the list already. It's partially a cultural difference. The notion that fewer words is better originated in American writing in the 19th century. The same metric does not hold in all languages or all readers/writers of English. As one example, Pascal, JP and I debated it a lot: I always thought fewer words is better, while their opinion, coming from French, was that more text typically adds greater larit.

>  
> 4.2 – Loop Avoidance (from section 3.8, RPL)     
> >       “rank-based datapath validation mechanisms”
>  
> Despite the fact this section is a repeat of elsewhere (see #5), this is a great example of what I mean. The first phrase is a less clear way of saying either “validating rank” or even better “checking packets are moving in the intended direction”. Of course a “rank-based datapath validation mechanism” sounds like more of an achievement than either of those two.
>  
> 4.3 – Greediness (from section 3.8.1, RPL)
> All of section 3.8.1/3.8.1.1 seems unnecessary. RPL doesn’t allow greediness – case closed. If you want to learn about greediness in general the RPL draft isn’t the location.
>  
> 4.4 – Introduction (section 1, 1.2, RPL)
> Of course, ‘satisfying constraints’. Wait, isn’t minimizing energy and minimizing latency also satisfying a constraint?
>  
> >   RPL
> Was this a contest to write the words “different link layers” in as many words as possible?
>  
> This is mostly a problem in section 3. Lots of information is repeated in different locations, which just makes it longer and more confusing.
>  
> Consider section 3.8 and section 3.3.7. They are both in the overview and deal with loops, and basically say the same thing. There’s some more loop stuff later even in section 3.8.2, but it’s at least a tiny bit different!
>  
> Throughout most of the introduction there is similar things. Section 3.7 has two paragraphs about the objective function, but then there is also a separate paragraph in section 3.3.1 about the objective function. Further it seems random if ‘Objective Function’, ‘OF’, ‘Objective Function (OF)’, or ‘objective function’ is used in the whole document.
>  
> There’s plenty more but I haven’t gone through everything. My comments here are purely on how the draft is written, nothing technical. I’m not sure how the IETF works but hopefully we could clean this up a lot without affecting LC, since it’s not actually changing any packet formats or logic.

No document is ever perfect -- it can always be improved by editing. It's great that someone is taking a fresh look. As I'm sure you know, when you've been writing and rewriting for a long time, you can lose context and perspective.

Phil

---

From: "Monnerie, Emmanuel" <[email-masked]>
Date: Thu, 19 Aug 2010 14:11:49 -0400

I don't know what the French culture has to do with it. I'm French and I
do believe that fewer words are better, particularly when it comes to
engineering documentation. If we were writing an essay or a piece of
literature, I would argue the opposite.

So I agree with Colin: many sentences are overly complicated.

Furthermore, the text is repeating several times similar statements,
which causes even more confusion. For example, look how many times the
word "RPLInstanceID" is defined throughout the text.

Best Regards

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of
Philip Levis
Sent: Thursday, August 19, 2010 12:58 PM
To: Colin O'Flynn
Cc: [email-masked]
Subject: Re: [Roll] English usage in I-D's

> Amazingly there is two sentences in there; the first one makes sense
but is a little complicated, the second one has five commas and seems to
be written by two different people about half-way through.

Colin -- we have had this discussion on the list already. It's partially
a cultural difference. The notion that fewer words is better originated
in American writing in the 19th century. The same metric does not hold
in all languages or all readers/writers of English. As one example,
Pascal, JP and I debated it a lot: I always thought fewer words is
better, while their opinion, coming from French, was that more text
typically adds greater larit.

Emmanuel Monnerie
Senior Research Engineer
Landis+Gyr
Energy Management Solutions
Office: +1 678 258 1695
Fax: +1 678 258 1316
[email-masked]
www.landisgyr.com
manage energy better

---

From: Alexandru Petrescu <[email-masked]>
Date: Thu, 19 Aug 2010 21:37:58 +0200

(yet another non native English speaker here)

I want to share my thought that I have similar feeling of too long text, 
often hard to read in draft-ietf-roll-rpl-11.

Sometimes words are written but not needed:
>   o  When mapping/transposing an IPv6 ND option for redistribution as a
>       RPL option

"Transposing" appears only here, "mapping" would be sufficient.

"Flag" (typically a 1-bit value) appears here but is wrong, DTSN being 
8-bit:
>   Destination Advertisement Trigger Sequence Number (DTSN):  8-bit
>          unsigned integer set by the node issuing the DIO message.  The
>          Destination Advertisement Trigger Sequence Number (DTSN) flag

Use of "transcribed for convenience" is doubtful:
>    [RFC4861] and [RFC3775] should be consulted as the authoritative
>    reference with respect to the Prefix Information option.  The field
>    descriptions are transcribed here for convenience:
>
>    Option Type:  0x08 (to be confirmed by IANA)

But RFC4861 says that field is 3, not 0x08 - who is right?

(besides, in that paragraph, "rfc4861" is not clickable whereas rfc3775 
is - I guess this is an error in the xml source text).

 > RPL supports two
 >    modes of downward traffic: storing (fully stateful) or non-storing
 >    (fully source routed).

"fully stateful" reads unnecessarily stressing the word "full", could 
have been better as "entirely stateful".

> 17.2.1. Initialization Mode
>
>
>    "Architectural Principles of the Internet" [RFC1958], Section 3.8,
>    states: "Avoid options and parameters whenever possible.  Any options
>    and parameters should be configured or negotiated dynamically rather
>    than manually.  This is especially true in LLNs where the number of

Missing ending double quote?

> In both cases, P2P packets travel Up toward a DODAG
>    Root then Down to the final destination (unless the destination is on
>    the upward route).

Does that "unless" mean that if the destination is on the upward route 
then the packets travel first downward and then upward?  Or does it mean 
there is no downward travelling if the destination were on the upward 
route?  I guess the latter, but it would be better to clarify.

There are many details like this, I noted some here and there.

Alex

Le 19/08/2010 20:11, Monnerie, Emmanuel a écrit :
> _______________________________________________
> Roll mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/roll
>

---

From: <[email-masked]>
Date: Thu, 19 Aug 2010 20:52:18 +0100

On 19 Aug 2010, at 17:58, Philip Levis wrote:

> Colin -- we have had this discussion on the list already. It's partially a cultural difference. The notion that fewer words is better originated in American writing in the 19th century.

It did not.

"I would have written a shorter letter, but I did not have the time.", Blaise Pascal, Provincial Letters: Letter XVI, 17th century.

"less is more" is pithy, but came later (Robert Browning, Andrea del Sarto, 1855. Again, not America.)

One can also make the case for stonemasons desiring brevity, and thus for the ten commandments.

> The same metric does not hold in all languages or all readers/writers of English. As one example, Pascal, JP and I debated it a lot: I always thought fewer words is better, while their opinion, coming from French, was that more text typically adds greater larit.

What is "larit"? I suspect you've completely undermined your own argument here.

Last I checked, the IETF was predominantly American culture. (Wasn't OSI French?)

I didn't bother reading ROLL drafts - they make little sense. Instead, I started with the terminology draft as a primer. Comments on that below.

http://tools.ietf.org/html/draft-ietf-roll-terminology
should say

   Terminology specific to a particular application *IS* out of the scope
   of this document.

   For example, an actuator might control and/or *MODULATE* the flow 

   Controller: A field device that can receive sensor input and
   automatically change the environment in the facility
-- what is the facility?

   Field Device: A field *DEVICE* is a physical device placed in the
   network's operating environment (e.g. plant, urban or home).  

   Field
   devices include sensors, actuators as well as routers and Low power
   and Lossy Network Border Router (including LBR). 
-- ugh. LBR is defined later. Rewrite.

   HVAC: Heating, Ventilation and Air Conditioning.  A term applied to
   the comfort level of an internal space.
-- The HVAC industry may disagree with that definition.

The LBR acts as a routing device and may possibly host
   other functions such as data collector or aggregator.
-- "may possibly" is perhaps slightly redundant and repetitive, in that it
says the same thing more than once? That is, twice?

   Open Loop Control: A process whereby a plant operator manually
   manipulates an actuator over the network where the decision is
   influenced by information sensed by field devices.
-- that is not open-loop control. The key point about open loop is
   that there is no feedback. See any control theory textbook.

  PER: Packet Error Rate.  A ratio of the number of unusable packets
   (not received at all, or received in error- even after any applicable
   error correction has been applied) to the total number of packets
   that would have been been received in the absence of errors.
-- No. A rate (X per second) is not a ratio (X/total). Learn the difference.
   (Admittedly, a lot of IEEE authors writing papers are unclear on this
   difference. And PERs are generally useless to engineers unless packets
   are all the same length. I blame the network simulator ns for introducing
   this concept widely.)

   Sensed data can be of many types: electromagnetic
   (e.g. current, voltage, power, resistance, ...) , mechanical (e.g.
   pressure, flow, liquid density, humidity, ...), chemical (e.g.
   oxygen, carbon monoxide, ...), acoustic (e.g. noise, ultrasound), ...
-- humidity sensors are generally capacitative, and therefore electrical. Also often the case for liquid density.

   Smart Grid: A Smart Grid is a broad class of applications to network
   and automate utility infrastructure.
-- just an application? Really???

   Timeslot: A Timeslot is a fixed time interval that may be used for
   the transmission or reception of a packet between two field devices.
   A timeslot used for communications is associated with a slotted-link
-- sentence incomplete.

I read the abstract of the ROLL rpl draft:

   Low power and Lossy Networks (LLNs) are a class of network in which
   both the routers and their interconnect are constrained: LLN routers
   typically operate with constraints on (any subset of) processing
   power, memory and energy (battery), and their interconnects are
   characterized by (any subset of) high loss rates, low data rates and
   instability. 

That's three separate sentences joined together for no good reason.
I did not read further.

Lloyd Wood
[email-masked]
http://sat-net.com/L.Wood

---

From: Philip Levis <[email-masked]>
Date: Thu, 19 Aug 2010 13:13:33 -0700

> One can also make the case for stonemasons desiring brevity, and thus for the ten commandments.

This is a fallacy of generalization. A few quotations from individuals who perhaps saw beyond their time do not indicate a general sentiment. I'll happily take the corpus of 19th-century and earlier literature as evidence before the opinions of a few. I realize that what I said was a gross generalization and the real history of English prose is far more nuanced and complex; I did not think that this is the right forum to discuss how Latin grammar and style influences Western writing.

That being said....

Writing is hard. Any text can always be improved. The question an author faces is whether the added effort is worth the gains. At some point, editing must end, or nothing will ever finish.

I can -- just as others have done -- take any non-trivial piece of text and point out possible improvements. As part of a genuine discussion on how to improve the text, those comments are always worthwhile. I can promise you that a series of detailed suggestions and editorial comments would be applied. Unfortunately, general comments such as "increase brevity" are difficult to act upon. Nobody is arguing that the text should be more voluminous or fluffy. Rather, the consensus of the WG and opinion of the shepherd was that the text was "good enough."

Phil

---

From: <[email-masked]>
Date: Thu, 19 Aug 2010 21:26:22 +0100

Brevity is the best recommendation of speech, whether in a senator or an orator.
-- Marcus Tulius Cicero (106-43 BC)

TL;DR

Lloyd Wood
[email-masked]

---

From: Alexandru Petrescu <[email-masked]>
Date: Thu, 19 Aug 2010 23:35:51 +0200

Le 19/08/2010 22:13, Philip Levis a écrit :
>
> On Aug 19, 2010, at 12:52 PM,<[email-masked]>  wrote:
>
>>
>>> Colin -- we have had this discussion on the list already. It's
>>> partially a cultural difference. The notion that fewer words is
>>> better originated in American writing in the 19th century.
>>
>> It did not.
>>
>> "I would have written a shorter letter, but I did not have the
>> time.", Blaise Pascal, Provincial Letters: Letter XVI, 17th
>> century.
>>
> This is a fallacy of generalization. A few quotations from
> individuals who perhaps saw beyond their time do not indicate a
> general sentiment. I'll happily take the corpus of 19th-century and
> earlier literature as evidence before the opinions of a few. I
> realize that what I said was a gross generalization and the real
> history of English prose is far more nuanced and complex; I did not
> think that this is the right forum to discuss how Latin grammar and
> style influences Western writing.
>
> That being said....
>
> Writing is hard. Any text can always be improved. The question an
> author faces is whether the added effort is worth the gains.
>
> At some point, editing must end, or nothing will ever finish.

That is also true.

> I can -- just as others have done -- take any non-trivial piece of
> text and point out possible improvements. As part of a genuine
> discussion on how to improve the text, those comments are always
> worthwhile. I can promise you that a series of detailed suggestions
> and editorial comments would be applied. Unfortunately, general
> comments such as "increase brevity" are difficult to act upon.

Well, yes, it is difficult, but in the past RPL draft did see such an
increase in brevity: from the 99 pages of version -2 to 82 pages of -4.
  That was a good thing, I think.

Here are some additional ideas:

Find in the ToC the sections taking much more pages than every other,
understand why, and question their usefulness.

In RPL-11 all 167 1-, 2- and 3-level sections are indexed at a
difference between 1 and  3 pages.  Except sections 6.1 and 8.2.2 each 5
pages long.  One wonders why are these 2 particular sections so long
compared to the 165 others?  They don't seem to describe core behaviour.
  Is there a way to reduce them?

Eliminate the RPLInstanceID concept.  The core protocol would work
without: run several "instances" of Unix processes, PIDs.

Join InstanceID, DAGID, DAGVersionNumber and DAGVersion into one ID.
For some reason they read as a very similar thing to one reader.

More ways: reuse IPsec AH security, and don't describe confidentiality
(encryption) at all - that would reduce some text.  Because instead of
specifying a secure version for each RPL message (section 6.1 taking 5
pages), AH covers a payload whatever that is, one single text sprinkled
here and there with short details of mutable fields, like the Checksum.

Remove section 10.3 - it's called "Installing Keys" but it doesn't say how.

> Nobody is arguing that the text should be more voluminous or fluffy.
> Rather, the consensus of the WG and opinion of the shepherd was that
> the text was "good enough."

That is ok too.

Alex

>
> Phil _______________________________________________ Roll mailing
> list [email-masked] https://www.ietf.org/mailman/listinfo/roll
>

---

From: "Colin O'Flynn" <[email-masked]>
Date: Thu, 19 Aug 2010 22:55:01 +0100

Hello,

> Yes, that description was added.

Excellent, exactly what I was looking for.

> The same metric does not hold in all languages or all readers/writers of 
> English.

I honestly don't think it's a cultural thing. You literally see it all the
time where stuff is excessively complicated, in all sorts of fields. In
America it's more commonly associated with "executive speak". But the
academic field is just as bad the world over, I can guarantee you. Consider
for example SCIgen (http://pdos.csail.mit.edu/scigen/) which generated an
accepted academic paper by purposely generating all sorts of babble.

> No document is ever perfect -- it can always be improved by editing.

This is not simple editing mistakes such as "that should be a semi-colon,
not a comma". Multiple sections literally define the same stuff, under
different section names (see my initial e-mail). Part of the document makes
a grand introduction to what greediness is, why it's bad, how it happens,
then simply says the user doesn't need to worry about it because it can't
happen. 

Again the core problems aren't even that the language itself is too
'academic'. It's that stuff is redefined, defined using different wording,
or completely unnecessary. This isn't a 'cultural' difference, be it
academic/commercial or French/American culture. 

It's always been more difficult to write a concise, short document. RPL
as-is seems great as a draft stage, where you've got all the technical stuff
down. But as a final standard, I couldn't imagine it to be acceptable... 

Warm Regards,

  -Colin

-----Original Message-----
From: Philip Levis [mailto:[email-masked]] 
Sent: August 19, 2010 5:58 PM
To: Colin O'Flynn
Cc: [email-masked]
Subject: Re: [Roll] English usage in I-D's

On Aug 19, 2010, at 7:35 AM, Colin O'Flynn wrote:

> Hello,
>  
> I finally got time to catching up on some of the latest I-D's. I'm a
little taken back by the complexity of English used in the drafts,
especially references to more academic things and just all-around
inconsistency.
> There is even a chance to confuse people IN the field! Why not either
define what is meant by writing it out, or use something like 'a <= x < b'?
I see a note that a 'natural langauge' description will be added which makes
sense hopefully...

This section was very carefully worded. Please note that the definition of
what constitutes a consistent transmission is an optimization method: it
leads to suppression, reducing communication and energy expenditure. If a
node does not suppress (e.g., k=infinity, defines nothing as consistent),
then it simply transmits every interval. In contrast, the definition of what
is *inconsistent* is critical for correctness. Hence the inconsistencies
being defined as MUSTs.

of
> Amazingly there is two sentences in there; the first one makes sense but
is a little complicated, the second one has five commas and seems to be
written by two different people about half-way through.

Colin -- we have had this discussion on the list already. It's partially a
cultural difference. The notion that fewer words is better originated in
American writing in the 19th century. The same metric does not hold in all
languages or all readers/writers of English. As one example, Pascal, JP and
I debated it a lot: I always thought fewer words is better, while their
opinion, coming from French, was that more text typically adds greater
larit.

> All of section 3.8.1/3.8.1.1 seems unnecessary. RPL doesn't allow
greediness - case closed. If you want to learn about greediness in general
the RPL draft isn't the location.
words as possible?
>  
> Throughout most of the introduction there is similar things. Section 3.7
has two paragraphs about the objective function, but then there is also a
separate paragraph in section 3.3.1 about the objective function. Further it
seems random if 'Objective Function', 'OF', 'Objective Function (OF)', or
'objective function' is used in the whole document.
>  
> There's plenty more but I haven't gone through everything. My comments
here are purely on how the draft is written, nothing technical. I'm not sure
how the IETF works but hopefully we could clean this up a lot without
affecting LC, since it's not actually changing any packet formats or logic.

No document is ever perfect -- it can always be improved by editing. It's
great that someone is taking a fresh look. As I'm sure you know, when you've
been writing and rewriting for a long time, you can lose context and
perspective.

Phil

---

From: "Monnerie, Emmanuel" <[email-masked]>
Date: Fri, 20 Aug 2010 10:51:08 -0400

Philip,

In order to avoid a flood of long emails, could we consider sending the
RPL author team an annotated document (MS Word format) including mostly
editorial comments?

Regards

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of
Philip Levis
Sent: Thursday, August 19, 2010 4:14 PM
To: [email-masked]
Cc: [email-masked]
Subject: Re: [Roll] English usage in I-D's

[...]

I can -- just as others have done -- take any non-trivial piece of text
and point out possible improvements. As part of a genuine discussion on
how to improve the text, those comments are always worthwhile. I can
promise you that a series of detailed suggestions and editorial comments
would be applied. Unfortunately, general comments such as "increase
brevity" are difficult to act upon. Nobody is arguing that the text
should be more voluminous or fluffy. Rather, the consensus of the WG and
opinion of the shepherd was that the text was "good enough."

Phil

Emmanuel Monnerie
Senior Research Engineer
Landis+Gyr

---

From: Philip Levis <[email-masked]>
Date: Fri, 20 Aug 2010 13:57:22 -0700

> RPL author team an annotated document (MS Word format) including mostly

Summary: I'd leave it to Tim and Pascal (editors) and David (chair) to decide.

Long-winded:

Well, I think that would be up to the editors (Pascal and Tim). Note that the document has passed last call and is now on to the IESG, so major rewritings are problematic. A huge list of edits on a 100+ page document might be difficult to apply, as I'm sure you realize: the resulting document would of course then need to go through an additional editorial pass for consistency and correctness, etc. 

Furthermore, it's worth saying that there isn't a single "true" way to write a document with as varied a readership and domain as this one. For example, a document that's clear, concise, and comprehensible to an expert in LLNs can be inscrutable to someone who's used to wired networks. Conversely, a document that's clear and concise to a wired network designer might seem verbose and long-winded to an LLN expert. 

Phil