paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-11-02 13:03:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Reorganize developer docs to improve navigation.

Browse Source 
This commit helps reduce clutter on the navigation sidebar.
Creates new directories and moves relevant files into them.
Modifies index.rst, symlinks, and image paths accordingly.

This commit also enables expandable/collapsible navigation items,
renames files in docs/development and docs/production,
modifies /tools/test-documentation so that it overrides a theme setting,
Also updates links to other docs, file paths in the codebase that point
to developer documents, and files that should be excluded from lint tests.

Note that this commit does not update direct links to
zulip.readthedocs.io in the codebase; those will be resolved in an
upcoming follow-up commit (it'll be easier to verify all the links
once this is merged and ReadTheDocs is updated).

Fixes #5265.
This commit is contained in:
David Rosa Tamsen
2017-11-08 10:55:36 -06:00
committed by Tim Abbott
parent 3b95a6d2d9
commit 7072fa5b37
123 changed files with 450 additions and 386 deletions
Download Patch File Download Diff File Expand all files Collapse all files

85
docs/contributing/accessibility.md Normal file
View File

@@ -0,0 +1,85 @@
# Accessibility
## Guidelines
In order to accommodate all users, Zulip strives to implement accessibility
best practices in its user interface. There are many aspects to accessibility;
here are some of the more important ones to keep in mind.
* All images should have alternative text attributes for the benefit of users
who cannot see them (this includes users who are utilizing a voice interface
to free up their eyes to look at something else instead).
* The entire application should be usable via a keyboard (many users are unable
to use a mouse, and many accessibility aids emulate a keyboard).
* Text should have good enough contrast against the background to enable
even users with moderate visual impairment to be able to read it.
* [ARIA](https://www.w3.org/WAI/intro/aria) (Accessible Rich Internet
Application) attributes should be used appropriately to enable screen
readers and other alternative interfaces to navigate the application
effectively.
There are many different standards for accessibility, but the most relevant
one for Zulip is the W3C's [WCAG](https://www.w3.org/TR/WCAG20/) (Web Content
Accessibility Guidelines), currently at version 2.0. Whenever practical, we
should strive for compliance with the AA level of this specification.
(The W3C itself
[recommends not trying](https://www.w3.org/TR/UNDERSTANDING-WCAG20/conformance.html#uc-conf-req1-head)
to comply with the highest AAA level for an entire web site or application,
as it is not possible for some content.)
## Tools
There are tools available to automatically audit a web page for compliance
with many of the WCAG guidelines. Here are some of the more useful ones:
* [Accessibility Developer Tools][chrome-webstore]
This open source Chrome extension from Google adds an accessibility audit to
the "Audits" tab of the Chrome Developer Tools. The audit is performed
against the page's DOM via JavaScript, allowing it to identify some issues
that a static HTML inspector would miss.
* [aXe](https://www.deque.com/products/axe/) An open source Chrome and Firefox
extension which runs a somewhat different set of checks than Google's Chrome
extension.
* [Wave](http://wave.webaim.org/) This web application takes a URL and loads
it in a frame, reporting on all the issues it finds with links to more
information. Has the advantage of not requiring installation, but requires
a URL which can be directly accessed by an external site.
* [Web Developer](http://chrispederick.com/work/web-developer/) This browser
extension has many useful features, including a convenient link for opening
the current URL in Wave to get an accessibility report.
Note that these tools cannot catch all possible accessibility problems, and
sometimes report false positives as well. They are a useful aid in quickly
identifying potential problems and checking for regressions, but their
recommendations should not be blindly obeyed.
## GitHub Issues
Problems with Zulip's accessibility should be reported as
[GitHub issues](https://github.com/zulip/zulip/issues) with the "accessibility"
label. This label can be added by entering the following text in a separate
comment on the issue:
@zulipbot label "accessibility"
If you want to help make Zulip more accessible, here is a list of the
[currently open accessibility issues][accessibility-issues].
## Additional Resources
For more information about making Zulip accessible to as many users as
possible, the following resources may be useful.
* [Font Awesome accessibility guide](http://fontawesome.io/accessibility/),
which is especially helpful since Zulip uses Font Awesome for its icons.
* [Web Content Accessibility Guidelines (WCAG) 2.0](https://www.w3.org/TR/WCAG/)
* [WAI-ARIA](https://www.w3.org/WAI/intro/aria) - Web Accessibility Initiative
Accessible Rich Internet Application Suite
* [WebAIM](http://webaim.org/) - Web Accessibility in Mind
* The [MDN page on accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility)
* The [Open edX Accessibility Guidelines][openedx-guidelines] for developers
[chrome-webstore]: https://chrome.google.com/webstore/detail/accessibility-developer-t/fpkknkljclfencbdbgkenhalefipecmb
[openedx-guidelines]: http://edx.readthedocs.io/projects/edx-developer-guide/en/latest/conventions/accessibility.html
[accessibility-issues]: https://github.com/zulip/zulip/issues?q=is%3Aissue+is%3Aopen+label%3A%22area%3A%20accessibility%22