Re: ACTION-108: RDFa Lite 1.1 Comments

On 01/17/2012 10:11 PM, Shane McCarron wrote:
> Disclaimer: I am an "Oxford Comma Nazi".

I seem to be surrounded by you people. :)

> Section 1:
>
> It says "The goal was..." I think it should be "The goal is...".
> Active voice. Present tense.

Fixed.

> Section 2.1 - the title should be "vocab, typeof, and property"

Fixed.

> paragraph 2 - "As you will note above, we have specified..." is
> awkward. How about "In this example we have specified..."

Fixed.

> Section 2.2
>
> It says "Uniform Resource Locator (URL)" Do we still say URL? I
> thought it was URI? or IRI?

Beginning web authors are going to be reading this document, and rather
than confuse them with the URI/IRI/URL distinction, I used what I think
is the most colloquial form of saying "identifier" among Web authors -
"URL". I checked the document for consistency and believe we use "URL"
everywhere.

> Section 2.3
>
> says "such as|dc|,|foaf|and|schema|." It should be "such
> as|dc|,|foaf,|and|schema|."

Fixed.

> Section 3:
>
> This sentence "As well as sections marked as non-normative, all
> authoring guidelines, diagrams, examples, and notes in this
> specification are non-normative. Everything else in this
> specification is normative." is awkward.

That is the boilerplate ReSpec text for the conformance section.

> How about "All authoring guidelines, diagrams, examples, and notes
> in this specification are non-normative. Sections marked specifically
> as 'non-nomative' are also non-normative. Everything else in this
> specification is normative."

If we are going to change this, I suggest we change it in ReSpec. I
think the wording is fine, but will trip up Editors who forget to mark
all of their non-normative sections with class="informative".

Thoughts?

> Section 3.1:
>
> It says "In order for a document to be labeled as a conforming*RDFa
> Lite 1.1 document*, it/must/provide the facilities described as
> mandatory in its Host Language and it/must not/use any additional
> RDFa attributes other than those described in this specification"
> This isn't quite right. I think we mean "In order for a document to
> be labeled as a conforming*RDFa Lite 1.1 document*, it/must/only
> require the facilities described as mandatory in its Host Language
> and it/must not/use any additional RDFa attributes other than those
> described in this specification"

Fixed.

Thank you for taking the time to review this document, Shane (and
Ivan!). Please let us know if these changes have satisfied your concerns
by Wednesday, February 1st 2012 (the day before we decide to enter the
Last Call period).

-- manu

-- 
Manu Sporny (skype: msporny, twitter: manusporny)
Founder/CEO - Digital Bazaar, Inc.
blog: PaySwarm vs. OpenTransact Shootout
http://manu.sporny.org/2011/web-payments-comparison/

Received on Saturday, 21 January 2012 20:28:37 UTC