p2: Purely editorial feedback

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/

Received on Saturday, 20 April 2013 07:40:16 UTC