Re: [access-control] editorial comments

Hi Anne,

Thanks for the reply.  I've trimmed it a bit and inserted my own  
comments inline.  Again, no need to do anything based on these  
comments, I just appreciate getting comments back when I write  
something, so :)


>> RFC 2119 keywords have a suggested markup in the guide that works  
>> well, since it puts them in italics and lower case using CSS, but  
>> fails back to capitalized, see
>
> I think the fallback to emphazing (which is also used when RFC 2119  
> is reference) is good enough.

Yeah, but the idea is that for someone reading with a text browser or  
a screen reader, etc, it would still be emphasized, thus:
http://www.w3.org/TR/2007/WD-access-control-20070618/,text

would show 'MUST' where appropriate (but still have lower case)


>> Reference tags and links should probably be done in the fashion  
>> mentioned in []
>
> Isn't this already the case?

Honestly, I can't quite recall what I was looking for here...

Ah, perhaps I meant they should appear within the sentence rather  
than done at the end.  The Manual of Style only has one example,  
which has both the words referenced and the reference at the end, so  
I'm not sure what is recommended.  (... looking up examples, sees  
that the DOM level 1 second edition incorrectly does things like  
'...Amendment 1 of [ISO/IEC 10646]'... ) OK, since I can't find an  
example ATM, I'll just be quiet :)

>> Section by section editorial thoughts:
>>
>> SoTD:
>> Is this a Rec track document?  I think that should be made clear  
>> here.
>
> Any suggestions on how to do that? FWIW, I looked around to other  
> drafts of which I know they are headed for Rec at some point in  
> time and they don't have it either (css3-multicol, XMLHttpRequest).

Ah, I sent an email right after sending my first comment [1], when I  
realized I was in error that it's required.  But, Thomas did chime in  
and say he thought it good anyways [2].

Something along the lines of:
"It is expected that this document will progress along the  
Recommendation process."
perhaps?

>> 1:
>> I'm not sure why the Conformance section is within the  
>> Introduction, or why Terminology is within Conformance?  Is the  
>> introduction informative or normative?
>
> Everything sentence with an RFC2119 term in it (properly marked up)  
> is normative.

What about the first question above about why Conformance is within  
the Introduction and Terminology within Conformance?

>> 1.1.1:
>> The terminology section might be expanded to add conventions on  
>> the use of color as well as adding some more of the terms used  
>> within.
>
> I'm not sure what this means.

I would like to see the stuff you said about the meanings of the  
color in the rest of this message (that is the bits that are colored  
that you expect to survive the entire process) have the meaning  
defined in the terminology section. e.g.:

"Portions of sample code may appear yellow in order to highlight the..."


>> The document ends abruptly.  I don't think there's much more to  
>> say, it just seems a bit abrupt.  I would like to see maybe an  
>> appendix where the inline EBNFs and perhaps a more formal  
>> representation of the algorithm could be placed for handy  
>> reference for implementors.
>
> I'd rather have implementors study the draft than use shortcuts as  
> using shortcuts leads to errors which you
> do not want here. However, if someone procudes something like that  
> it might be worth considering.

Good point.  It's easy when writing this stuff to make it "reviewer  
friendly", which is not always the same as implementor friendly.   
It's kind of like "teaching to the test".


Thanks for taking the time to read and respond!

I look forward to discussing this some more with the POWDER group.

Cheers,

-Matt Womer
POWDER Team Contact


[1] http://lists.w3.org/Archives/Public/public-appformats/2007Jul/ 
0028.html
[2] http://lists.w3.org/Archives/Public/public-appformats/2007Jul/ 
0029.html

Received on Monday, 30 July 2007 19:12:40 UTC