Editorial comments on webarch 21 March 2003

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Here are my editorial suggestions for the 21 March draft, which I
quite like on the whole.

If I think the suggested change is important, I've tried to explain
why. If I haven't tried to explain why, then I'm just correcting a
typographic or grammatical mistake or I think it reads better with the
change I've suggested.

General notes:

  There's inconsistency about the capitalization of words in section
  titles. I think we should use the traditional style and capitalize
  all significant words, but I can live with a different style as long
  as we apply it consistently.

Abstract:

  s/and design choices/and choices/ in the second sentence

    To avoid the word "design" appearing twice in the same sentence.

1. Introduction:

  s/This document organizes/This document describes/

  s/Mexico wishes/Mexico and wishes/ in the paragraph that begins "Suppose Dan..."

  Also in that paragraph, the fragid #weather in the URI appears in the wrong
  font.

1.1 Summary

  s/Conneg/Content negotiation/

    Abbreviations are likely to be confusing, especially to readers for whom
    English is a secondary language.

  s/principles should guide/principles could guide/ in the "Understand REST" principle

    I think one "considers" what could be done, not what should be done.
    (Yes, one likely considers whether or not what could be done should be done,
     but I don't think that's what this principle is trying to say.)

  s/limited uniform/limited, uniform/ in the last bullet of that principle

  s/and so education/in which case education/ in the paragraph that immediately follows

    I think "and so" is a bit informal.

  s/behind some of good/behind some good/ in the next paragraph

2. About this document

  The paragraph after the list ends "will elaborate on the required properties,
  constraints, and principles, rationale, and additional examples". I suggest:

    ...will elaborate on the rationale behind the properties,
    constraints, and principles described in this document and will
    provide additional examples.


  s/document is the result/document is principally the result/ in the
  last paragraph of section 2 (immediately before 2.1)

2.1 Scope

  s/reader is familiar with rationale/reader is familiar with the rationale/

  s/: minimal constraint/: minimal constraints/


3.1 Comparing identifiers

  I think the wording of the "spelling URIs" principle is confusing. I suggest
  instead:

    Spelling URIs: There is some flexibility in the way URIs can be
    spelled. For example, RFC2396 provides a mechanism by which some
    characters can be encoded directly or in an escaped form. Specific
    URI schemes may introduce the possibility of other variation as
    well. If you want to refer to a resource, and you have been provided
    with a URI for that purpose, you SHOULD use the spelling of the URI
    as it was originally provided.

  If that's too long, I suggest this wording:

    Spelling URIs: If you want to refer to a resource, and you have
    been provided with a URI for that purpose, you SHOULD use the
    spelling of the URI as it was originally provided.

  Additionally, I propose the following rewording of the paragraphs
  that follow the principle:

    Producers of URIs should be conservative about the number of
    different URIs they produce for the same resource. To that end,
    they should maximize the consistency of identifiers that they use.
    Conversely, they should ensure sufficient difference between
    identifiers used for different resources to minimize the
    possibility of consumers losing the distinction.

    Consumers of URIs, on the other hand, should interpret URIs as
    liberally as possible. Even though producers should not use
    http://example.com/MyStuff and http://example.com/myStuff to
    identify different resources, they may, and clients that assume
    that these URIs refer to the same resource do so at their own
    risk.

3.2 URI Schemes

  The two lists in this section are used for the same general purpose,
  but they look quite different. I think it would be better if they
  were marked up the same way.

3.4.1 Retrieving a representation

  s/"define the semantics/"defines the semantics/ in the first
  numbered list item.

  Since the example describes an 'a' element in an SVG document, I
  really think the current item '3' in the list should be item '1'.
  Otherwise, how did we get to the URI in the first place?

3.4.3 Identification is not access

  This section seems to "start in the middle" of something. In fact,
  my first suggestion was going to be that it should be merged into
  the preceding section. But after more thought, I do think it
  deserves its own section.

  Try reading it on its own and see if you don't agree that it needs a
  little better introduction.

  I also think that it overstates the case just a little bit at the
  moment. Secrecy *is* a reasonable component of restricting access to
  information. It happens, for example, that the entire content of my
  Palm is on the web. It's on a server that requires authentication
  and I've tried reasonably hard to secure it, but I sleep better at
  night knowing that those mechanisms are rarely tested because no one
  knows where it is.

3.4.4 Servicing a URI

  s/interactions via that/interactions with that/

  s/depend on (at least) time, the/depend on (at least) the/

    I think saying time is redundant. If the representation depends on
    the weather in Oaxaca and the weather in Oaxaca is inherently
    dependent on time, the representation is already dependent on
    time. Saying it twice makes me think that it depends on time for some
    reason *other* than the weather in Oaxaca.

  s/two images as equivalents through/two images as equivalent through/

  In the very last sentence of section 3.4.4, there's a reference to
  Cool URIs Don't Change. It strikes me that that's an important
  enough concept to the stability of the web architecture that we
  really ought to incorporate that content into this document. Am I
  wrong?

4. Representations

  s/describe a resource state/describe a resource's state/

  s/Date about the resource,/The data constituting the representation/

    I think it's strange to speak of the actual content of the
    representation as data "about" the representation when we
    immediately follow that with a discussion of metadata which is, by
    natural definition of the word metadata, data about the
    representation.

  Delete the sentence "One would expect a representation of the weather in
  Oaxaca to vary over time" from the last paragraph before the ednote.
  It's redundant since we've already dealt with it at length in section 3.4.4.

4.3.1 When to use XML

  s/Persistence/Longevity/ in list item 2.

     We've already talked about persistence in a different sense, so let's
     use a different word here.

4.4 Separating Content and Presentation

  s/for example, restyling a pie diagram to fit into a different presentation/
  for example, resizing a pie diagram to fit into a different presentation window/

  s/and the decision made to display/and the decision has been made to display/
  in the last paragraph.

5. Machine-to-machine interaction

  s/It is also not static/It is not static/

  Also, delete the spaces around the hyphens in that sentence and turn them
  into proper &emdash;s.

6.1 Information hiding

  s/system, avoidable references/system, references/

    The references are harmful or they aren't. They're also avoidable
    or they aren't. They aren't less harmful when they're not avoidable,
    there's just nothing you can do about those.

  In the second paragraph, delete the sentence that begins "However,
  there is a flaw..." It's irrelevant to the topic at hand and might
  conceivably be fixed in the future.

                                        Be seeing you,
                                          norm

- -- 
Norman.Walsh@Sun.COM    | If you imagine that once you have
XML Standards Architect | accomplished your ambitions you will have
Web Tech. and Standards | time to turn to the Way, you will discover
Sun Microsystems, Inc.  | that your ambitions never come to an
                        | end.--Yoshida Kenko
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: Processed by Mailcrypt 3.5.7 <http://mailcrypt.sourceforge.net/>

iD8DBQE+2l2DOyltUcwYWjsRAgn8AKCJKZ25CW+FUTSTfxN5pDfamIVH2ACglbs5
UGCIA9blmINMtkWjvozvuFY=
=Stix
-----END PGP SIGNATURE-----

Received on Sunday, 1 June 2003 16:09:54 UTC