Re: p2: Purely editorial feedback

[Mark Nottingham <[e-mail]>]

Now:
  http://trac.tools.ietf.org/wg/httpbis/trac/ticket/450


On 20/04/2013, at 5:39 PM, Mark Nottingham <[e-mail]> wrote:

> Strictly editorial feedback on the current p2:
> 
> * 1. Introduction doesn't read smoothly. I'm happy to make a proposal if necessary. 
> 
> * 2 "The target of each HTTP request"   s/each/a/
> 
> * 3.1 "The following header fields are defined to convey representation metadata:"  This reads as if it's a closed set. Suggest removing "are defined to".
> 
> * 3.1.1 a more appropriate section title would be "Processing Representation Data" or "Processing Representation Metadata" (depending on intent)
> 
> * 3.1.2.1 "Frequently, the representation is stored in coded form, transmitted directly, and only decoded by the recipient."   Saying "final recipient" would be clearer.
> 
> * 3.1.4.1 "...by other means (not defined by HTTP)..." --> "...by other means (not defined by this document)..."  (two occurrences) 
> 
> * 3.4.1. "When content negotiation preferences are sent by the user agent in a request in order to encourage..."   The use of "in order" is slightly confusing here, esp. to a non-native speaker; we don't want to imply that they're ordered.  Suggest dropping "in order".
> 
> * 4.1 Last paragraph - "A client can send conditional request header fields..."   Suggest prefixing with "For example," and moving up to be after the first paragraph.
> 
> * 4.3.5 "action seems okay" is too informal.
> 
> * 4.3.7 "The OPTIONS method requests information about the communication options available on the request/response chain identified by the effective request URI."  This can be misread; suggest:
> 
> "The OPTIONS method requests information about the communications options available for the target resource, either at the origin server or an intervening intermediary."
> 
> * 5.3 should be a subsection of 3.4.1; there are already a number of headers defined in section 3, and it's better to have all of the conneg material together.
> 
> * 6.5.8 "...could not be completed due to a conflict with the current state of the resource." --> "... with the current state of the target resource."
> 
> Cheers,
> 
> 
> --
> Mark Nottingham   http://www.mnot.net/
> 
> 
> 
> 

--
Mark Nottingham   http://www.mnot.net/