Closed Bug 315402 Opened 19 years ago Closed 18 years ago

Create Accessibility section in Help Documentation

Categories

(Firefox Graveyard :: Help Documentation, defect, P2)

defect

Tracking

(Not tracked)

RESOLVED FIXED
Firefox 2 beta1

People

(Reporter: mdfft, Assigned: pilgrim)

References

Details

(Keywords: access, fixed1.8.1)

Attachments

(1 file, 5 obsolete files)

Description: 

An Accessibility Section is needed in the Firefox Documentation.  Here are some considerations for writing this section:

The accessibility help should be aimed at the end user as the audience.  The real issue here is that there is some accessibility features documented in some places.  They all need to be accumulated into one place.  For example, if I say "toggling images" should be documented, even if it is documented somewhere else, it needs to be specifically in the accessibility section.  It should be  one stop shop for all accessibility questions.  Now, since keyboard bindings are documented and the section is quite large a link to the section within the accessibility help should suffice.  Some starting points can be:

- Link to keyboard bindings 
- Toggle Images, javascript, audio/video playback, etc
- Changing and overriding text/background colors/fonts/sizes
- Setting FIrefox to use system fonts and colors as opposed to its own or the web pages fonts and colors.
- Section on what is possible to accomplish with changing stylesheets.
- If accessibility extensions are going to be considered, provide instructions that will help the user obtain accessibility extensions. Then Provide Keyboard binding information for the extensions
- How to use the search function, for instance document that ctrl+g performs a "find again", since this is not an expected keyboard shortcut.
- Section on how to configure Firefox to handle Tabbed Browsing.
- Section on enabling caret browsing, and clipboard features.
- Section documenting the profiles functionality of firefox and how to create, change, and invoke them.  As well as how accessibility features are affected, i.e. user defined style sheets
- Blocking popups

Separate subsections for the following may be helpful
- FireFox features for accessibility ( overall picture, keyboard access)
- Customization for accessibility (color, font, toolbars if any )
- Any new features that might help accessibility  or features that work different. ( like the find feature which works a little differently, tabbed browsing)
- Any advance features
Priority: -- → P2
Where to look for assistive technologies that work with Firefox ... screen readers, screen magnifiers, voice input software, on screen keyboards, etc.
Blocks: uaag
Keywords: access
Summary: Create Accessibility section in Documentation → Create Accessibility section in Help Documentation
If we get this section we should also mention it in the documentation section of Firefox's VPAT (Section 508 compliance statement).
Assignee: nobody → pilgrim
Status: NEW → ASSIGNED
OS: Windows XP → All
Hardware: PC → All
Target Milestone: Firefox1.5 → Firefox 2 alpha2
Version: 1.5 Branch → Trunk
Depends on: 328812
Attachment #211937 - Attachment is obsolete: true
Attachment #211938 - Attachment is obsolete: true
Attachment #213900 - Flags: review?(mconnor)
Attachment #213901 - Flags: review?(mconnor)
Comment on attachment 213901 [details] [diff] [review]
browser/locales/en-US/chrome/help/accessibility.xhtml

(A note: you don't need to obsolete patches before posting new versions.  When you upload a patch you can have it obsolete other patches and thus reduce the created bugspam.)


First, some general documentation and style issues:

Limit lines to 80 or fewer characters to make printing the code easier.  If a line's contents exceed this length, wrap the text and indent all subsequent continuations by two spaces.  For example:

>   <p>This is a really long line which is going to exceed 80 characters by quite a bit

...should be changed to:

>   <p>This is a really long line which is going to exceed
>     80 characters by quite a bit

(Note: that's probably not actually wrapped at 80 characters because I didn't count them -- you get the idea, though.)

If a line must exceed this length for structural reasons (e.g., a long hyperlink on a line which is already indented), then wrap as early as possible after 80 characters.  (This currently isn't actually applied to RDF for any of the help datasources, so don't worry about them in the other patch.)  Note also that this makes reviewing attachments easier; without wraps, the reviewer must manually break up lines unless he wants the entire line displayed (and without wrapping, because Bugzilla doesn't wrap quoted text in attachment "edits").

Regarding indentation, we usually indent an amount corresponding to the depth in the tree for all elements below <head/> or <body/>, so for a heading and the paragraphs immediately following it the <p/> tag should be aligned with the <hx/> tag.

The custom for referring to "Firefox" is to refer to it as "Mozilla Firefox" once at the start of each document (or twice if the document title refers to Firefox) to reinforce branding.  Subsequent references should simply be to "Firefox" for succinctness.  The patch mostly follows this guideline, but there's one instance where this guideline isn't applied.  (By the way, thanks for using the branding entities!)

The full set of documented guidelines (there are probably some that should be added) we mostly follow are at the following two links:

http://www.mozilla.org/projects/help-viewer/documentation_language-style
http://www.mozilla.org/projects/help-viewer/documentation_coding-style

Now, more specific comments:


>	<link rel="stylesheet" type="text/css" href="chrome://help/skin/helpFileLayout.css"/>
><style type="text/css">
>dd p {
>  margin-top: 0;
>}
></style>

I agree that the default top margins here are a bit big by default, but seeing as the only place where this occurs is in single-line definitions, why not just make the <dd/> elements directly contain their child text?


>  <h3 id="keyboard_shortcuts">Keyboard Shortcuts</h3>
>    <p>This help file contains <a href="shortcuts.xhtml">a
> list of common keyboard shortcuts</a>.</p>
>
>    <p>Online, you can find <a target="_blank"
> href="http://www.mozilla.org/support/firefox/keyboard">a
> comparison chart of keyboard shortcuts</a> implemented in
> &brandFullName;, Microsoft Internet Explorer, and Opera.</p>

Could these two paragraphs be combined together?  I generally try to avoid single-sentence paragraphs if at all possible.  Also, &brandFullName; should be &brandShortName; because it's not immediately at the beginning of the document.


>    <p><q>Caret browsing</q>

In general help documentation uses <em/> when referring to UI (e.g., buttons, labels in forms, etc.), so please use that when referring to UI (except for menu paths, which you've already covered :-) ).  If you're referring to a feature, the only particularly well-defined convention is to make it a link if possible; for example, this should be a link to the relevant option in prefs.xhtml.  (Or should that include a link here?  Maybe for another bug...)


> You can enable this feature in &pref.menuPath;<span
> class="menuPath"> &gt; Advanced &gt; General &gt; Accessibility</span>.</p>

The style for referring to panels/UI/etc. in options is the following:

"You can enable this feature by selecting &pref.menuPath;, opening the <em>General</em> tab in the <em>Advanced</em> panel, and checking the <em>Allow text to be selected with the keyboard</em> &pref.singular;."

I agree it's not the best way to refer to specific preference UI and is perhaps overly verbose, but it's what we use now.  (There are more instances of your style in the doc which I won't point out to save space.)

Additionally, if you can figure out a good way to work in a link to that preference here, feel free to do so; I'm not sure whether it can be done, but feel free to give it a shot.


> You can disable this prompt by selecting <q>Don't show this dialog again.</q></p>

<em/> here, please, too.  (I'm going to stop mentioning this because it's a concern common to most of the patch, and doing so interferes with other comments.)


>  <h3 id="typeahead_find">Find As You Type</h3>

Nit: try to keep ids the same as contents of the id with spaces replaced by "_" and extra words removed.  This isn't a hard-and-fast rule, but it's usually preferable to keep ids sane.  This applies most other places in this file, too.


>    <p><q>Find as you type</q>

This should be a link to the preference UI.


> text or hyperlinks in a web page, without opening a separate dialog.

Please drop the comma in this sentence; it's unnecessary.


> <q>Find as you type</q>

I'd prefer if this and all future references to fayt weren't <q/>, but as long as it's not a link I'm not sure it's that critical that it be changed.


> <li>&brandShortName; will highlight the next matching
> hyperlink or text, or alert you that nothing matched.</li>

Please remove the comma here; "alert you that nothing matched" is a complete clause and shouldn't be separated from the beginning of the sentence.


>      <li>Press &accelKey;<kbd>+G</kbd> or <kbd>F3</kbd>
> to find the next occurrence of your current search string.</li>
>      <li>Press &accelKey;<kbd>+Shift+G</kbd> or <kbd>Shift+F3</kbd>
> to find the previous occurrence of your current search string.</li>

Please enclose each separate key in the command within a <kbd/>, and don't enclose the concatenating "+" within <kbd/>.  Also, please use &shiftKey; for Shift for better modifier key readability.  (Note that &ctrlKey;, &shiftKey;, &altKey;, and &accelKey; are all defined such that their text is enclosed in <kbd/>, so you don't need to wrap them.  By the way, thanks also for noticing and taking the time to use the entities!)


>      <li>Press <kbd>Backspace</kbd> to undo the last
> character you typed.  &brandShortName; will back up to
> the previously highlighted text.</li>

None of the people who write help documentation have Macs :-( , so I could be wrong here, but I think on Macs Backspace is actually "Delete".  Please find someone with a Mac to double-check that the key name and behavior are correct or incorrect on Macs.


>      <li>Press <kbd>Escape</kbd> to cancel a search.

Please use "Esc" here, because it's what the keyboard shortcuts docs use.


> By default, auto-started

You don't need the comma here.


> before the control you want, then press <kbd>Tab</kbd>.

Please replace ", then" with "and".


> and sets focus to the next control

Can we come up with a better term here than "control"?  "form control" would be better, but I still don't particularly like it.


>    <p>This help file contains <a href="mouse_shortcuts.xhtml">a
> list of common mouse shortcuts</a>.</p>

I'd rather avoid referring to the help file itself here; how about:

"A full list of available mouse shortcuts is available in <a href="mouse_shortcuts.xhtml">&brandShortName; Mouse Shortcuts</a>."


> Some web sites may define fonts that are difficult for
> some users to read,

Could you remove "for some users" here?  See also my comment on "some users" further down.


> Content</span>.  In the <q>Fonts &amp; Colors</q> section,
> you can select a default font and size.</p>

This could be shortened to "Content</span> and selecting a default font and size in the <em>Fonts &amp; Colors</em> section.".


> <em>deselect</em> <q>Allow pages to

Help docs use "uncheck" for checkboxes, and we generally don't emphasize "uncheck", either.


>    <p>Some web sites may define fonts that are too small
> for some users to read.

I'm not sure I like "some users" (because it's specifically singling those users out as "different" and possibly "less capable") or "define fonts" (slightly technical language).  How about "Some web sites may use text which is too small to be read comfortably."?


> To make such pages more accessible, you can set a minimum font size.
> On web pages that try to display text smaller than the minimum font
> size, &brandShortName; will enlarge the text to the minimum font
> size.</p>

Can this be rewritten without using "minimum font size" three times?  Also, I'd prefer the less-buzzwordy "readable" to "accessible" here.


> Here you can specify a minimum font size.</p>

This sentence feels a bit abrupt, but I'm unsure how it should be changed.


>    <p>Some web pages that make assumptions about available
> font sizes may display incorrectly if you set a minimum font size.</p>

How about the less verbose "Note that some pages may display incorrectly depending on your choice of a minimum font size"?


>    <p>You can temporarily change the size of text on a web
> page in the <span class="menuPath">View &gt; Text Size</span>
> menu.  Unlike some other browsers, &brandShortName; can resize
> text on any web page.

The "Unlike some other browsers" part here is unnecessary, but if you're afraid users may be accustomed to that particular bug in a certain other browser, change "text on a web page" to "text on any web page" in the previous sentence.


> The new size will remain in effect until you close your
> browser window, even if you navigate to a different web site.</p>

Internally, changed font sizes are a per-docshell (i.e. per-tab or per-window) property.  Consequently, if you open a link from a tab in which you've increased font size the new page won't use the altered text size.  Could you mention this here, please?


>    <p>There are also keyboard shortcuts for controlling text size.</p>

"There are" is a weak start to a sentence; how about "The following keyboard shortcuts control text size:"?


>      <li>Press <kbd>Ctrl+plus</kbd> to increase the text size.
>  This zooms the text to 120% of its original size, then 150%,
> 200%, 300%, 450%, 675%, 1013%, and 1519%.</li>
>      <li>Press <kbd>Ctrl+minus</kbd> to decrease the text size.
>  This zooms the text to 90% of its original size, then 50%, 33%,
> 22%, 15%, 10%, 7%, 4%, 3%, 2%, and 1%.</li>
>      <li>Press <kbd>Ctrl+0</kbd> to reset the text size to the
> default value defined by the web page.</li>

Do we really need to list percentage sizes here?  It's an implementation detail, and I'd really prefer that we didn't.  These commands are only supposed to make text "bigger" and "smaller".  Note also that a more extensive menu involving actual changes existed in the Mozilla Suite, but it was removed precisely because that level of detail is unnecessary in the vast majority of cases.

Also, please change the shortcuts to use "+" and "-" (with an <abbr/> if you want -- that's a good idea we should probably implement in the shortcuts docs sometime, actually), use &accelKey; or &ctrlKey; depending on whether Cmd++ or Ctrl++ works on Macs, and don't include the concatenating "+" in <kbd/>.


>    <p>Some web pages that make assumptions about font sizes
> may display incorrectly if you change the text size.</p>

How about the slightly less verbose "Note that some web pages will not display correctly if you change their text size."?


> deselect <q>Allow pages to choose their own colors,

"uncheck" instead of "deselect", please.


> are using a High Contrast theme, and displays everything in your

Remove the comma here, please.


>    <p>This help file contains <a href="popup.xhtml">information
> on controlling popup windows</a>.</p>

Same thing here wrt self-references to help; how about:

"See <a href-"popup.xhtml">Controlling Popups</a> for information on allowing and disabling popups."


> Java&#8482;

Documentation editors who don't know the Unicode codepoints aren't going to have a clue what this is; &trade; is a much more readable alternative.


> to the rest of the web page.</p>
>    <p>If this is a problem for you, you can disable Java

These two paragraphs should be merged, because the second is just a continuation of the first.


><h2 id="extensions">Accessibility-Related Extensions</h2>

Firefox Help has strictly avoided ever referring to extensions by name for reasons of liability, the unreliability of updates, and the possibility of obsolescence as new versions of Firefox emerge.  If you wish to provide a list like this, please place it in a separate document online where it can be updated as new extensions are created, updated, and released.  Note also that you must be online to install these extensions anyway, so moving the documentation online shouldn't be particularly onerous.


> <a href="http://www.mozilla.org/access/compatibility">

Policy question: should this be on mozilla.com?


>  <p class="win">Freedom Scientific maintains a number
> of <a href="http://www.freedomscientific.com/fs_support/User_Groups.asp">mailing
> lists for JAWS users</a>.</p>
>
>  <p class="win">GW Micro maintains a number of <a
> href="http://www.gwmicro.com/Support/Email_Lists/">mailing
> lists for Window Eyes users</a>.</p>

Nit: enclose these in <div class="win"/> and remove the individual-element styles.  Alternatively, you could also combine these into one paragraph.


>  <p>You may <span class="win">also</span> post accessibility
> questions to the <a href="http://forums.mozillazine.org/viewforum.php?f=38">&brandFullName;
> Support forum</a>.</p>

It would be preferable to link to a mozilla.org/com page (or even a redirect) for control over this link in the unlikely event that MozillaZine forums suddenly became inaccessible for whatever reason.


><div class="contentsBox"><em>3 March 2006</em></div>
><p>Copyright &copy; 2003-2006

Should this be changed to just "2006"?  It's been too long since any new help documents were written, so I'm not sure whether this is correct.
Comment on attachment 213901 [details] [diff] [review]
browser/locales/en-US/chrome/help/accessibility.xhtml

To generate a patch for new files, use cvsdo from cvsutils, e.g. 'cvsdo add <filename>', and then cvs diff -uN <filename>.

Additional drive-by comment: We have to use the terminology of the UI, e.g. "Allow text to be selected with the keyboard" instead of "Caret Browsing", and "Begin finding when you begin typing" instead of "Find As You Type".

Please request review for patches regarding Help Documentation from Jeff or myself (but stick to Jeff in this bug).
Attachment #213901 - Flags: review?(mconnor)
Addressed all of Jeff's concerns from comment 7 and Steffen's concerns from comment 8, except:

- I feel strongly that the exact text size percentages should be listed.  For the menu, it's fine to say "larger" and "smaller", but the audience that *relies* on this feature will appreciate more precise documentation.

- Didn't change the mozilla.org link because Aaron Leventhal owns the entire mozilla.org/access subtree.  If we move it, we'll have to set up a 301 redirect anyway, but I don't want that to hold up this bug.
Attachment #213900 - Attachment is obsolete: true
Attachment #213901 - Attachment is obsolete: true
Attachment #218876 - Flags: review?
Attachment #213900 - Flags: review?(mconnor)
Attachment #218876 - Flags: review? → review?(jwalden+fxhelp)
Whiteboard: [review needed]
Comment on attachment 218876 [details] [diff] [review]
Accessibility help topic file and TOC patch

I haven't heard anything from Jeff lately, so I'm having a look instead.

You've got to add the new accessibility.xhtml to mozilla/browser/locales/jar.mn to get it shipped.

>Index: browser/locales/en-US/chrome/help/accessibility.xhtml
>+  <h1>Accessibility Features of &brandFullName;</h1>
>+
>+  <p>&brandFullName; includes many features to make the browser and web content
We use brandFullName usually only once in the document, so use brandShortName here.

>+  <p><a href="prefs.xhtml#accessibility">Begin finding when you begin
>+    typing</a> allows you to quickly navigate to text or hyperlinks in
>+    a web page without opening a separate dialog.  This feature has two
remove "without opening a separate dialog".

>+  <p>Immediately after the default font and size selection, you can click
>+    the <em>Advanced...</em> button to specify default fonts for different
>+    styles, including serif, sans-serif, and monospace.  However, many web
I'd rephrase like this: You can specify default fonts (...) by clicking the Advanced button.

>+  <p>To set a minimum font size, go to &pref.menuPath; and select the
>+    <em>Content</em> panel.  In the <em>Fonts &amp;
>+    Colors</em> section, immediately after the default font and size
>+    selection, click the <em>Advanced</em> button.  You can specify a
>+    minimum font size from the dropdown menu.</p>
I like this as short as possible: go to ..., select the Content panel, and click the Advanced button in the Fonts and Colors section.

>+  <p>Some web sites may display text and background colors that are
>+    difficult to read, and other sites may rely on the browser's default
>+    colors.  You can set your default colors by going to &pref.menuPath;
>+    and selecting the <em>Content</em> panel.  In
>+    the <em>Fonts &amp; Colors</em> section, click the
>+    <em>Colors...</em> button.  Here you can set default text and
by going to ..., selecting the Content panel, and clicking the Colors... button in the Fonts&Colors section.

>+  <p>The latest information about compatibility with third-party assistive
>+    technologies is online at
>+    <a href="http://www.mozilla.org/access/compatibility">Access Mozilla:
>+    Compatibility with assistive technologies</a>.</p>
target="_blank"

>+    <p>Freedom Scientific maintains a number of
>+      <a href="http://www.freedomscientific.com/fs_support/User_Groups.asp">mailing
>+      lists for JAWS users</a>.</p>
target="_blank"

>+    <p>GW Micro maintains a number of
>+      <a href="http://www.gwmicro.com/Support/Email_Lists/">mailing lists
>+      for Window Eyes users</a>.</p>
target="_blank"

>+  <p>You may <span class="win">also</span> post accessibility questions to the
>+    <a href="http://forums.mozillazine.org/viewforum.php?f=38">&brandShortName;
>+    Support forum</a>.</p>
target="_blank", and "MozillaZine Support forum".

>Index: browser/locales/en-US/chrome/help/firebird-toc.rdf
Er, most of the links don't match the ids in accessibility.xhtml. In other words, they're broken.
Attachment #218876 - Flags: review?(jwalden+fxhelp) → review-
Whiteboard: [review needed]
Incorporates all review items from comment 10.
Attachment #218876 - Attachment is obsolete: true
Attachment #222902 - Flags: review?
Attachment #222902 - Flags: review? → review?(steffen.wilberg)
Comment on attachment 222902 [details] [diff] [review]
Accessibility help topic

Great, thanks a lot! r+a=me.
Attachment #222902 - Flags: review?(steffen.wilberg)
Attachment #222902 - Flags: review+
Attachment #222902 - Flags: approval-branch-1.8.1+
Whiteboard: [checkin needed]
Checked in trunk & branch.
Status: ASSIGNED → RESOLVED
Closed: 18 years ago
Resolution: --- → FIXED
Whiteboard: [checkin needed]
Target Milestone: Firefox 2 alpha2 → Firefox 2 beta1
> http://www.mozilla.org/access/compatibility
> This address does not exist.
Uh, I thought I tried all the links. But I can't find it in the bonsai-www history. Mark, Aaron, do you have a new url or should we remove it altogether? "The latest information about compatibility with third-party assistive technologies is online at: <broken link>Access Mozilla: Compatibility with assistive technologies</broken link>".
(In reply to comment #15)
> > http://www.mozilla.org/access/compatibility
> > This address does not exist.
> Uh, I thought I tried all the links. But I can't find it in the bonsai-www
> history. Mark, Aaron, do you have a new url or should we remove it altogether?
> "The latest information about compatibility with third-party assistive
> technologies is online at: <broken link>Access Mozilla: Compatibility with
> assistive technologies</broken link>".

We don't have such a document, and if we did, I would suggest putting it on a Wiki, because people will be more likely to maintain it. The closest thing we have is http://www.mozilla.org/access/features
Sorry, this is my fault.  I will post the page shortly at the given URL.

I feel strongly that such a compatibility page should *not* be on a wiki.  Compatibility with third-party products has the potential to become a politically charged topic, and someone needs to take final responsibility for the information that we're linking to from the local help pages.  If the information falls out of date or people have some other beef with the compatibility page, they can open a bug report about it, and we'll all discuss it.  I'm more comfortable with that kind of audit trail than with relying on a wiki revision history.

I do not, however, care whether the compatibility page lives on mozilla.org or mozilla.com.  If someone cares enough to make a case for .com over .org, I would be happy to post a separate patch to change the local help page.
Status: RESOLVED → REOPENED
Resolution: FIXED → ---
Blocks: fox2access
Do we need any restrictions or guidelines for localizers and which pages/websites they should/can link to?
For this, linking to mozilla.com would be good, as we intend to create a localization scheme including fallback to English there.
Depends on: 345363
I'm marking this fixed again since this bug is finished and localizers shouldn't hesitate start translating it. I filed 345363 about adding the missing document.

Regarding external links, we have these:
1. http://www.mozilla.org/access/compatibility (Access Mozilla: Compatibility with assistive technologies; see bug 345363)
2. http://www.freedomscientific.com/fs_support/User_Groups.asp (mailing lists for JAWS users)
3. http://www.gwmicro.com/Support/Email_Lists/ (mailing lists for Window Eyes users)
4. http://forums.mozillazine.org/viewforum.php?f=38 (Firefox Support Forum)

#2 offers to subscribe to mailing lists in a few languages. But the page itself is English only.
#3 contains links to mailing lists for a few different languages. Some of the links are broken though...
So localizers could either link to the English pages, or find local equivalents, or remove those links.

#4 could be replaced by a local forum.
Status: REOPENED → RESOLVED
Closed: 18 years ago18 years ago
Keywords: fixed1.8.1
Resolution: --- → FIXED
Product: Firefox → Firefox Graveyard
You need to log in before you can comment on or make changes to this bug.

Attachment

General

Created:
Updated:
Size: