Re: minor comments for UA Guidelines and Techniques 20000310

Susan Lesch wrote:
> 
> For the UA Guidelines' Proposed Recommendation Last Call, these are a
> few minor editorial comments for the Guidelines [1], Checklists
> [2,3], and Techniques [4] "work in progress."

Thanks Susan!

I will integrate all of these. A couple of your comments reveal
minor bugs in the document production mechanism (e.g., point 3
below is a script issue, as is the duplication of checkpoint 5.3
in the checklist).

Thanks for your willingness to do a second review unprompted!!

I will incorporate all of your points. I've deleted most
of your comments in this reply, but left a few for comment.

  - Ian
 
> Three notes on style:
> 
> 1. Personally (and I did not list them here), I try to eliminate
> "slash/pairs" when possible; this joining/construct may mean
> something for "and/or", but choosing the most pertinent term, or
> combining terms with hyphens or conjunctions strikes me as a more
> precise way to express a pair of ideas.

I haven't made any changes here, but will review.
 
[snip]
 
> 3. I wasn't sure if you wish to cut down on markup overhead by
> eliminating links to the glossary from the checkpoints, so I didn't
> list those links. For many of the checkpoints, glossary items are
> anchors without class .dfn-instance markup. For example, in 2.
> Guideline 1 checkpoint 1.1, API is <a href="#def-api">API</a> but in
> the paragraph before the checkpoints, API is <a href="#def-api"
> rel="glossary" title="Definition of  Application Programming
> Interface (API)"><span class="dfn-instance">APIs</span></a>.

Script bug that's been fixed.


I've made a global change of "header" to "heading" for H1 - H6. The
term "header" should now only be used for HTTP headers and table
headers.

> Guidelines
> ----------
> 
> 1.2 Ensure that the user interface is accessible - 2nd to last par.,
> and 1.4 par. 1 (twice), 2. par. 1, 6.1 Note, and 3. Recognize, and in
> Techniques Appendix 6 for Recognize
> Techniques Document
> Techniques document [This is my best guess for capitalization.]

I've changed to "Techniques document" globally.

[snip] 

> 1.7 Well-formed conformance claims - last par.
> http://somewhere.com/checkpoints
> [somewhere.com is a registered domain. You could consider using
> example.com, example.net, or example.org instead, which IANA reserved
> for examples. See RFC 2606 section 3 [5].]

ok.
 
> Checklists
> ----------
> 
> Checkpoint 11.1
> [[WCAG10]]
> <a href="#ref-WCAG10" title="Link to reference WCAG10">[WCAG10]</a>

I've added a references section to the checklists, so this will work.
 
> Checkpoint 5.3 is repeated.

Script bug that's been fixed.

> Techniques
> ----------
> 
> At least the first time it's mentioned, "Internet Explorer [IE]"
> maybe could say "Internet Explorer for Windows 95, Windows 98, and
> Windows NT [IE-WIN]". There is a Macintosh version (5.0 ships this
> month) and I presume Windows and Unix versions.

Ok. I should probably add version information for each piece of
software. Hmm, Todo...

[snip]
 
> 2. end of Guideline 5.9, and Appendix 9.1
> "Microsoft Active Accessibility" [MSAA].
> apparently moved to http://www.microsoft.com/enable/msaa/default.htm

Yes.

 
> "The Inter-Client communication conventions manual" [ICCCM].
> [Might help to know which file to look for in this FTP directory.]

icccm.ms. I've added that it's troff format.
 
> "Accessibility for applications designers" [MS-ENABLE].
> [The first link (http://www.microsoft.com/enable/dev/apps.htm) moved
> with no forwarding address evident. The second link (as listed in
> Appendix 9.1), "Built-in accessibility features", connects.]

Now http://www.microsoft.com/enable/dev/guidelines/software.htm.
Too bad the MS Webmasters are breaking links. <frown>
 
[snip]
> 
> 3.1.3 - 3rd to last list item
> [QUICKTIME]
> [Looks like it needs a References link. Could be
[ http://www.apple.com/quicktime/] 

Document markup bug. You're right, and it will be there.

[snip]


> 3.4 par. 2
> Use compound numbers (or letters, numbers, etc.) to introduce each list item
> [You may have discussed this and I missed it. Would this principle
> apply to Checkpoints in the table of contents for UA Guidelines and
> Techniques?]

This is a tricky one and we've had this comment before. I don't
want the TOC to read "Section 2.1" for Guideline 2. I'd rather it
be "Section 2, Guideline 1". However, putting the word "Guideline"
in each entry of the TOC makes it kind of long, so only the
number appears there.

Suggestions welcome. We could put "G1" or something like that...
 
[snip]

> Best wishes for your project,

Thanks again Susan,

 _ Ian

-- 
Ian Jacobs (jacobs@w3.org)   http://www.w3.org/People/Jacobs
Tel:                         +1 831 429-8586
Cell:                        +1 917 450-8783

Received on Monday, 27 March 2000 16:06:30 UTC