Subject: Clarity of documents

From: Eric Burger <[email-masked]>
Date: Mon, 1 Jun 2009 07:26:27 -0400

[note subject change]

I agree with John - strict rules can create weird wording to satisfy  
the rules.  Since we are "talking" about prose here, it does need to  
be readable.

HOWEVER, I very much disagree that we should make standards documents  
easy to read through linguistic fun.  We want these documents to be  
precise, easily implementable, descriptions of protocols.  By their  
nature, they will be boring.  So be it.  Boring, accurate, and easy to  
implement wins over interesting, imprecise, and hard to determine  
exactly what the author meant.

On May 31, 2009, at 11:38 PM, Yaakov Stein wrote in Re: [IAB] Out of  
the box proposal
> The example does not prove anything about passive voice,
> it simply points out that we should not forget to address both  
> transmit and receive actions.
>
> I could say
>  Upon receiving X the receiver MUST perform Y
> or
>  Received Xs are handled by performing Y
> and although the second is in passive voice it means exactly the  
> same thing.
>
> Judicial use of passive voice breaks the monotony and may make the  
> document more "reader - friendly".
>
> BTW, pseudocode included in RFCs tends to be in procedural  
> (imperative) languages or pseudolanguages,
> and is thus in active voice.
>
> Were we to use a functional or declarative language
> then the specification would be in passive voice.
>
> Both imperative and declarative code can be unambiguous descriptions
> of the desired functionality.
>
> Y(J)S
>
>
> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]]  
> On Behalf Of DRAGE, Keith (Keith)
> Sent: Monday, June 01, 2009 03:24
> To: John C Klensin; Sandra Murphy; Eric Burger
> Cc: Working Group Chairs
> Subject: RE: [IAB] Out of the box proposal
>
> At the moment I don't think anyone is being prohibitive. What is  
> being pointed out is that most requirements (i.e. those that need  
> RFC 2119 language - no one has been referring to surrounding  
> informative text) are better written in the form
>
> 	<entity performing the action> MUST <verb> <action>
>
> because that form indicates clearly what has to perform what action.  
> Too many times readers are left guessing.
>
> That form also says that text of the form:
>
> 	The xyz message shall contain abc
>
> can be equally bad. The problem here is that it hides two potential  
> requirements, the sending requirement (to include abc), and the  
> receiving requirement. What to do if abc is not there, and what to  
> do with it if it is there. In many cases the receiving requirement  
> is handled by generic requirements elsewhere, but the absence of the  
> correct drafting of the requirement leads to confusion.
>
> Keith
>