Subject: Re: [apps-discuss] Review of draft-ietf-appsawg-uri-get-off-my-lawn

From: Mark Nottingham <[email-masked]>
Date: Tue, 28 Jan 2014 21:34:27 +1100

Hi again Tim,

See:
  https://github.com/mnot/I-D/commit/007b9b4

On 6 Dec 2013, at 5:22 pm, Tim Bray <[email-masked]> wrote:

> I think this should be published as a Best Common Practice soon as possible.
> 
> Minor issues:
> 
> * The title and introduction: 
> 
> “Standardising Structure in URIs“ is unfortunate because the central message is “Don’t try to standardize structure in URIs”. How about “Preserving URI Space Design Freedom” or “URI Structure Design Considered Harmful” or “URI Space Design Ownership” - I think that last one is a serious suggestion.

I like the latter, and have tweaked (since the above commit) to "URI Design and Ownership" -- sound good?

> 
> : This document cautions against this practice in standards (sometimes called "URI Squatting").
> 
> I’m not sure the “sometimes called” parenthetical really adds value, but if preserved, it should be moved to immediately after “this practice”. Also, the document doesn’t caution against it, it bristles with MUST NOTs.  How about “This document is intended to prevent the use of this practice (sometimes called "URI Squatting") in standards.”
> 
> * 1. Introduction
> 
> The bullet point beginning “Dilution” is grammatically strained.  The “extra information” is the subject of both verbs, so turn it around to read something like “Extra information, added to URIs to support standardization, dilutes their usefulness as ..., and causes alternate forms of the URI to exist.  And I’m not sure Dilution is the right label; the key point is weakening the URI’s utility as an identifier. Having said that I can’t think of a one-word alternative.

See how it looks now.

> In that list of bullet points, you might also want to add that query parameters are problematic for two more reasons: There’s not a good hook in 3986 to use to say what you’re talking about, and also you’re doing a parameter-name land-grab, which means you now have another design problem, you have to prefix or otherwise clutter your parameter names to in effect create a namespace for them.  Or worse, don’t.

I think this is covered by Collision, no?

> 
> 2nd-last para:  The phrase that begins “publishing standards that mandate URI structure is inappropriate... ” is the central tl;dr of this whole draft, very nicely crystallized. Could it be pulled out and featured in the introduction or even abstract?
> 
> * 2.
> 
> “Different components of a URI have differing practices recommended.” Passive voice, turn it around: “Best practices differ depending on the URI component”, or some such.
> 
> * 3.
> 
> I think you could just subtract this whole section and not much would be lost. I think you’re trying to hint at HATEOS without actually naming it.  In particular, I find the second paragraph entirely baffling, and have no idea what it’s trying to say.

I've trimmed and focused a bit.

Thanks again,

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