Documentation

Documentation usually gets a bad name in the world of engineering. It's challenging to maintain, difficult to write effectively and can quickly go out of date. So why try? Because it can help people work independently – and that's invaluable in the world of accessibility. So when we began writing documentation for accessibility, we started by mapping out guiding principles for its structure, and writing only for Facebook engineers let us focus the content.

This documentation uses an FAQ format, which is based on our experience supporting engineering (the only "content grouping" we do is by platform: iOS, Android, etc.) We don't cover all accessibility topics, just those we expect a generalist engineer to own. We don't expect a generalist engineer to become a student of ARIA’s history, so we omit it.

Here are some examples of things we expect a generalist engineer to own:

  1. Add labels to buttons
  2. Add alt text for static images
  3. Make sure UI elements get focus
  4. Use modern components from our Component Library
FAQ on adding support for high contrast mode

Here are some examples of things we don't expect a generalist engineer to own (but to instead work with those who have strong accessibility expertise):

  1. How to make a dynamic typeahead work in a screen reader
  2. How to design and enable a custom VoiceOver gesture

After we finished writing initial documentation that was unique to our infrastructure, we encouraged people to use it in their work. We knew the only way our documentation would be used consistently was if we linked to it in every accessibility engineering task. If you work on an accessibility task, you can’t miss seeing our documentation. It’s everywhere.

We also have component-specific documentation embedded in our component library (like how to add a coherent label for an Android TextView that takes a dynamic notification count). This is different from our general documentation framework, but we wanted accessibility information for components to live alongside them, not in an external documentation system.

Image-only button showing notification count on Android
Complementary accessibility description for example UI button with notifications

Documentation is a core part of our scaling strategy. Documentation can provide relevant support for real world accessibility tasks. It should be easy to read and focused on applied techniques. Documentation won’t solve everything, but it’ll help strengthen the foundation your engineering team builds on.

Keep Updated

Stay up-to-date via RSS with the latest open source project releases from Facebook, news from our Engineering teams, and upcoming events.

Subscribe
Facebook © 2017