Re: [whatwg/url] Add string UTF-8 percent encode (#503)

(Warning: This long comment may seem like getting into “how many angels can fit on head of pin” territory but is offered FWIW from my (long-ago) training and experience as a technical writer.) 

As far as use of hyphens/dashes in the operation names, some options to consider:

1. (which I recommend) Always hyphenate *percent-encode* and *percent-decode*, and:
   * Don’t put a hyphen before *percent-encode* or *percent-decode* in any operation name that just has a single qualifier; so “*UTF-8 percent-encode*” and “*string percent-encode*”.
   * Do put a hyphen before *percent-encode* or *percent-decode* in any operation name that has more than one qualifier; so ”*conditionally UTF-8-percent-encode*”.
2. Hyphenate everything: “*UTF-8-percent-encode*” and “*conditionally-UTF-8-percent-encode*” and “*UTF-8-percent-encode-with-userinfo-percent-encode-set*”.
3. Hyphenate nothing (except *UTF-8* of course, and except when “*percent-encode*” or “*percent-decode*” are adjectives): “*UTF-8 percent encode*” and “*conditionally UTF-8 percent encode*” and “*UTF-8 percent encode with userinfo percent-encode set*.

Option 2 above is most-clearly not the best choice in this case, because if you apply it, you end up with that “*UTF-8-percent-encode-with-userinfo-percent-encode-set*” monstrosity.

Option 3 is also sub-optimal in this case, since in the same operation name, you end up with both “*percent encode*” (unhyphenated) and “*percent-encode*” (hyphenated). That risks making readers stumble — because at first reading, it might seem odd/inconsistent (even though it really isn’t).

Option 1 in this case therefore kind of hits the sweet spot (given all of the above).

---

**Further rationale**

While there aren’t set-in-stone rules for when to add hyphens — it’s always partly a judgement call — the main guiding principle (especially in technical docs) is to add hyphens to avoid ambiguity; that is, to avoid having readers mis-read or mis-parse or stumble over a particular phrase.

That’s especially important in cases where what you’re hyphenating is a compound adjective — because those are the cases where there’s the greatest risk of ambiguity and misreading. It’s less important in cases where what you’re hyphenating is a noun or verb — which is essentially the case here, because these are operation names.

But another principle is consistency: If you know you’re otherwise gonna end up with cases like “*UTF-8 percent encode with userinfo percent-encode set*” — one operation name that has the same combination of words both unhyphenated (“*percent encode*”) and hyphenated (“*percent-encode*”) — then avoid that by just always hyphenating it.

And the final principle is: When you’ve ended up with some term that is itself referencing/qualifying some other multi-word term, use hyphens to make that more clear; so that’s what leads you to *“conditionally UTF-8-percent-encode”* rather than just *“conditionally UTF-8 percent-encode”*.
</details>

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/url/pull/503#issuecomment-627100358