Re: my action item on issue 52 (Sort 1.3 Terminology)

On Fri, 15 Jun 2007 14:37:21 +0200, Julian Reschke
<julian.reschke@gmx.de> wrote:

> 
> Julian Reschke wrote:
> > 
> > See <http://www.w3.org/Protocols/HTTP/1.1/rfc2616bis/issues/#i52>.
> > 
> > There was an open action item for me to sort the terminology
> > section, and to post the outcome over here for discussion (I'll add
> > my opinion in a separate mail).
> > ...
> 
> I personally think we should not do this change:
> 
> (1) Sorting paragraphs makes it very hard to verify the changes; in 
> essence, a reviewer would either need to trust us, or re-do the 
> shuffling to control whether it's correct (nothing lost, no change in 
> the definitions).

It's fairly trivial to verify: pick the original, copy the first
definition, go to the modified version, and search for those exact
contents. If the exact contents are present, move to the second
definition in the original; if they're not, reject it. Take a second
pass on the destination to verify that the alphabetical ordering is
correct. It's O(N), and a 45 minute editorial job at absolute tops;
5-15 if you have any skill with a good text editor. The only trip-up
would be page breaks, and that's easy to take care of by first removing
the page breaks/headers/footers from both the source and destination
(working on copies, of course).

> (2) In the RFC2616 ordering, things that belong together (such as 
> "client", "user agent", "server" ...) are close to each other.

The topical-closeness of the entries is very much subject to opinion.
Alphabetical ordering is unambiguous and objective; there is no
confusion as to whether "content negotiation" should be closer to
"origin server" or "cache" when sorted alphabetically. Furthermore,
all entries in the glossary are "close to each other" versus the
entirety of the document -- three full contiguous pages isn't a lot,
proportionally, but having to look up specific definitions over and
over and over again in an unsorted list gets _very_ obnoxious.

> (3) Contrary to RFC2616, the text version of new spec will contain an 
> alphabetical index section anyway (unless it's removed upon
> publication :-).

I was working off a hard-copy at the time I requested this change, and
let me tell you -- I'd sooner go look at the un-sorted glossary than
take *two* skips, one from my reading spot to the index, and then from
the index to the glossary. In this case, I'd completely avoid the index
for another reason: because the glossary is merely three (and a
half) pages long, I could bookmark the first page and find the entry I'm
looking for by scanning the whole list. It would be faster than looking
the term up in the index, finding the one-in-five pages the definition
could be on, and then scanning through the dozen entries on that page
to find the one I'm looking for. Indexing does not increase the speed
with which I find the information; alphabetizing would.

Alphabetizing is a well-established method for ordering glossaries,
indexes, and other data intended for quick retrieval. I believe that
alphabetizing the glossary will make the document much friendlier for
users, especially ones who want to ensure that they are stringently
following the meaning of these special words throughout the document.
It is a relatively cheap fix, and the work will result in a massive
savings of time, when aggregated over the number of lookups across all
readers.


-- 
Travis

Received on Friday, 15 June 2007 15:54:36 UTC