A11y-Friendly Documentation

A11y-Friendly Documentation

A talk focused on assistive technology and how to build accessible documentation.

Current deck from: Open Source 101
Recording: Coming soon!

8c5989329a85b590fecdb4f7a97cbe3a?s=128

Carolyn Stransky

May 12, 2020
Tweet

Transcript

  1. a11y-friendly documentation @carolstran bit.ly/a11y-docs-resources

  2. a11y @carolstran

  3. accessibility @carolstran bit.ly/a11y-numeronym

  4. @carolstran a11y bit.ly/a11y-numeronym

  5. @carolstran a11yproject.com

  6. @carolstran accessibility web accessibility degree to which an environment is

    usable by as many people as possible degree to which a website is usable by as many people as possible bit.ly/a11yfore
  7. @carolstran 1,000,000,000 World Health Organization bit.ly/who-at

  8. how people interact with the web @carolstran

  9. assistive technology @carolstran

  10. screen readers @carolstran • jaws - job access with speech

    • apple’s voiceover • microsoft’s narrator
  11. None
  12. None
  13. keyboard navigation @carolstran • specialist • custom • on-screen

  14. @carolstran bit.ly/shopify-dp

  15. navigation hardware @carolstran • touchscreens • mouth sticks • foot-operated

    mice
  16. switch inputs @carolstran • mechanical buttons • foot plates •

    electronic sensors
  17. trackers @carolstran • eye • head • dwell control

  18. @carolstran there's a business case for a11y bit.ly/w3-bcase

  19. but documentation is left out @carolstran

  20. “documentation is for developers” @carolstran

  21. One out of every 66 software developers is blind or

    hard of sight @carolstran StackOverflow Developer Survey bit.ly/so-devsurvey
  22. @carolstran Florian Beijers, freeCodeCamp “The tutorials are undoubtedly good, but

    were completely unreadable for me” bit.ly/fcc-florian
  23. @carolstran most of us are already doing it

  24. • logical layouts • user journeys • localization • cross-browser

    testing @carolstran
  25. @carolstran this is our responsibility

  26. @carolstran “We may or may not be responsible for writing

    the HTML, but if the developers we’re working with don’t produce semantic structure, then they’re not actually representing the structures that we’re building in our designs” Anne Gibson, independent consultant bit.ly/pfa-anne
  27. structure and hierarchy @carolstran

  28. @carolstran

  29. @carolstran

  30. html - hypertext markup language @carolstran bit.ly/a11yfore

  31. • h1 • nav • aside • ul / ol

    @carolstran
  32. @carolstran bit.ly/react-gs

  33. @carolstran bit.ly/react-gs

  34. aria - accessible rich internet applications @carolstran

  35. aria roles @carolstran <span role=“status"> Your changes were automatically saved.

    </span> bit.ly/mdn-aria
  36. aria properties @carolstran <div id=“newsletter”>Newsletter</div> <div> <div id=“email”>Email</div> <input type=“text”

    aria-labelledby=“newsletter email”/> </div> bit.ly/mdn-aria
  37. aria states @carolstran <span aria-hidden=“true”> There was an error. Please

    try again. </span> bit.ly/mdn-aria
  38. best for <div> and <span> elements @carolstran

  39. @carolstran focus indicators

  40. @carolstran bit.ly/stripe-connect

  41. • links • form fields • widgets • buttons •

    menu items @carolstran
  42. @carolstran gov.uk

  43. • can I tab through the page without getting lost?

    • do all focusable elements have focus states? • can I operate tabs, accordions, search results, etc with just my keyboard? • do I have a skip navigation link? @carolstran
  44. @carolstran skip links

  45. @carolstran twilio.com/docs

  46. @carolstran twilio.com/docs

  47. @carolstran developer.mozilla.org

  48. @carolstran images

  49. alt tags @carolstran

  50. @carolstran isthereuber.in

  51. @carolstran isthereuber.in

  52. @carolstran isthereuber.in

  53. 918e15484df8b5806e f5612f985260e9.svg @carolstran

  54. @carolstran <img alt=“” src=“globe.svg”>

  55. @carolstran charts and infographics

  56. • what are the highlights and lowlights of the graphic?

    • what are the most important and notable parts? @carolstran
  57. @carolstran 0 40 80 120 160 April May June July

  58. 0 40 80 120 160 April May June July @carolstran

    iOS vs Android Downloads
  59. 102 iOS downloads and 115 Android downloads occurred in April.

    143 iOS downloads and 126 Android downloads occurred in May. 27 iOS downloads and 18 Android downloads occurred in June. 124 iOS downloads and 138 Android downloads occurred in July. @carolstran
  60. 0 40 80 120 160 April May June July @carolstran

    iOS vs Android Downloads
  61. The lowest amount of downloads occurred in June, with 27

    iOS and 18 Android. @carolstran
  62. alt tag @carolstran

  63. @carolstran <svg role=“img” alt=“The lowest amount…”> ... </svg> bit.ly/charts-a11y

  64. @carolstran <svg role=“img” aria-label=“The lowest amount…”> ... </svg> bit.ly/charts-a11y

  65. @carolstran <svg role=“img” aria-label=“iOS vs Android Downloads” aria-describedby=“chart-desc”> <desc id=“chart-desc”>

    The lowest amount… </desc> ... </svg> bit.ly/charts-a11y
  66. @carolstran

  67. @carolstran trello.com

  68. @carolstran

  69. @carolstran

  70. bit.ly/charts-a11y

  71. @carolstran code snippets

  72. @carolstran if (x == true) { console.log(“hello world!”) } example

    if-block in JavaScript
  73. if left paren x equals equals true right paren left

    brace console dot log left paren quote hello world exclaim quote right paren right brace @carolstran the example if-statement read by a screen reader
  74. <code> @carolstran

  75. <code> @carolstran use meaningful variable names

  76. <code> @carolstran use meaningful variable names watch for extra spaces

  77. @carolstran inclusive writing

  78. plain language @carolstran

  79. @carolstran

  80. “No one has ever complained that something was too easy

    to read” @carolstran Ashley Bischoff, copy editor at The Paciello Group bit.ly/ashley-fronteers
  81. testing for accessibility @carolstran

  82. wcag - web content accessibility guidelines @carolstran

  83. @carolstran

  84. most assistive technologies are free or inexpensive @carolstran

  85. @carolstran

  86. @carolstran

  87. dev tools @carolstran • firefox • chrome • safari

  88. @carolstran

  89. free extensions and validators @carolstran

  90. @carolstran

  91. @carolstran bit.ly/vue-v2

  92. @carolstran

  93. @carolstran bit.ly/slack-integrations

  94. make accessibility a priority @carolstran

  95. create an accessibility policy @carolstran

  96. @carolstran

  97. update your development checklists @carolstran

  98. @carolstran

  99. browse the web from a different perspective @carolstran

  100. host an a11y hackathon @carolstran bit.ly/mdn-a11y-hack

  101. final thoughts @carolstran

  102. this is for everyone @carolstran bit.ly/govuk-dp

  103. documentation is for everyone @carolstran

  104. Ask questions in the chat or on Twitter @carolstran bit.ly/a11y-docs-resources