Re: Accessibility Guidelines

[Peter Korn <Peter.Korn@Sun.COM>]

Hi Michael, gang,

I have updated our Accessibility Guidelines document to "subcommittee 
draft 2", incorporating (I believe) all of Michaels comments below.  
This updated document is attached, and being uploaded to the SC page 
now.  This has resulted in a number of new glossary items, and the 
creation of hyperlinks for all glossary entries as well as styling 
changes in the main body text (italics and hyperlinks commonly show as 
blue text) to clearly indicate when some text is defined in the 
glossary.  Change tracking was turned on for these updates, to make it 
easy to locate the changes for anyone wanting to quickly see what I did.

I did not change the location of the glossary as Michael suggested - I 
felt that since we now have styling change and we also have a Glossary 
entry in the table of contents, that should be sufficient.

Michael - another OOo/SO question for you: what should I do to make 
Appendix A appear in the table of contents?  For some reason that isn't 
happening.


Regards,

Peter Korn
Accessibility Architect,
Sun Microsystems, Inc.

> Hi Peter,
>
> below are the few things I have noticed in the document:
>
> general: The document uses API names like "IAccessible", "GTK+" without
> providing references. Some, but not all are explained in the Glossary
> section, but I did notice that only after reading through the document.
> I'm not sure if we could provide references to all these APIs, but I
> think it would be helpful to add as many as possible if we want to 
> encourage developers to use the mentioned APIs in their products. I 
> further think it may be helpful if API names and/or
> glossary terms would use a different formatting (or style), and if the
> glossary is at the beginning of the document.
>
> general: the style used for attribute and element names is not
> consistent. Sometimes they appear in Courier (section 3.3), sometimes
> they appear with a variable font (section 4.1). Sometimes element names
> are in <> (section 4.1), sometimes they aren't (section 4.2.4).
>
> My recommendation would be to use a monospaced font, and to include
> elements in <>, since this is the style of the ODF specification. The
> ODF specification defines the character styles "element" and "attribute"
> for that purpose. If you use them, then we may run consistency checks 
> on the document that ensure that there are no spelling errors in the 
> element and attribute names.
>
> Section 3.1.2: The advice does not include to specify a proper tab
> order. Is that by intention?
>
> Section 3.1.5: The comment says soft page breaks are not contained in
> ODF 1.1. But they are.
>
> Section 3.1.6.1: Maybe we should say "ODF *1.1* does not support", since
> we know that they will be in 1.2.
>
> Section 4.3 states: "although ODF claims to use XForms it does not use
> XForms controls. In XForms, label would be a child of the form, which
> controls it labels." Since we never claimed to support XForms controls
> but only the XForms model with our own controls I would phrase this a
> little bit different.
>
> Section 4.4 "draw:caption-id" is an attribute, but appears within "<>".
>
> I further checked whether OASIS has a different template for informal 
> documents, but there seems to be none. There is only one for white 
> papers (see http://docs.oasis-open.org/templates/ at the end of the 
> page), but the guidelines document is not a white paper. Interesting 
> however is the statement at the bottom of the page: "TC chairs should 
> notify communications@oasis-open.org of approved white papers, so 
> their availability can be promoted in OASIS News." So, yes, we should 
> send out such a mail, or otherwise ask OASIS to announce the document 
> in their OASIS/XML news.
>
> Michael

ODF_Accessibility_Guidelines_scd2_25July2007.odt