The document discusses writing documentation with a focus on making it equitable and accessible for neurodivergent contributors. It emphasizes the importance of clear communication, avoiding jargon, and providing supportive structures like localization efforts and glossary sections. The author advocates for continuous improvement and inclusivity in the open source community to enhance contributions from diverse minds.

1. Writing Documentation with
Neurodivergent Open Source
Contributors in Mind

2. HELLO!
I’m Rin Oliver
I’m a Technical Community Builder at Camunda.
I use they/them pronouns.
You can find me on Twitter at @kiran_oliver, or
on GitHub at @celanthe.
2

3. Who am I?
⦿ I am multiply neurodivergent, and am autistic, have dyspraxia,
dyscalculia, and ADD.
⦿ I am a Member of Kubernetes, having previously participated in the
Contributor Experience SIG. I’ve spoken at Kubernetes Contributor
Summit 2019 and KubeCon EU 2020.
⌾ I’ve been involved in OSS in one way or another since 2015
⦿ I have been both a maintainer and a contributor to documentation
⦿ I am an advocate for improving the OSS contributor experience for
neurodivergent individuals 3

4. What is neurodiversity?
Neurodiversity is the diversity of human minds, the
infinite variation in neurocognitive functioning within
our species.
Dr. Nick Walker, Neurocosmopolitanism

5. Why this matters
Without having equitable and accessible documentation best practices for
writing, updating, and contributing to documentation--You may miss out on
contributions from neurodivergent individuals.
Thus, you’ll not get to learn from our unique perspectives, hear our ideas, and
listen to our strategies for improving your community and its documentation.
If you’ve met one neurodivergent individual, you’ve met just one of us. Imagine
how much more you might be missing out on.
5

6. GETTING
STARTED
How to get started writing
documentation with neurodivergent
individuals in mind!
6

7. Open source is hard to get into.
As the ‘hows’ are not very clear,
and neurodivergent people may
not understand the process that
easily. -- Participant, Smashing the Barriers to OSS
Contribution, Mozilla Festival 2019
7

8. Writing equitable and accessible documentation
⦿ Localization efforts are crucial
⦿ Don’t use jargon that is specific to your company or product in your
docs
⌾ If you can’t avoid jargon, have a glossary available with
up-to-date definitions of terms you use
⦿ Use positive language that encourages users and contributors
⦿ Set clear expectations of what documentation pull requests should
look like
8

9. Tips for implementation
⦿ Localization -- If someone approaches you requesting to translate your organization’s documentation, have
processes and procedures in place for supporting this! Have a section of your contributor guide dedicated to
localization efforts, how to get started, and best practices for docs localization teams.
⦿ Writing a glossary is helpful if you can’t avoid using company or industry specific jargon
⌾ Surface this on your site. Link to the glossary whenever a term is used that one may not be familiar
with.
⦿ Positive language can be thanking people for their contributions, encouraging them when they submit code for
review, and being compassionate and understanding rather than nitpicking.
⦿ Using templates for new pull requests and issues is a great way to make sure that pull requests coming in
adhere to your established style guide/linter/best practices, making them faster to review and merge.
9

10. BEST
PRACTICES
Keep these in mind when writing
documentation!
10

11. Helpful
⦿ Have a DRI (directly responsible individual)
people can go to with questions about your
product or documentation. Know who owns
updating particular sections of documentation.
⦿ Give environment setup or demo steps one at a
time
⦿ Clearly state which sections of your
documentation are accepting pull requests, if
any
What works, and what doesn’t
Not helpful
⦿ Rejecting documentation improvements that
got something, ‘Most of the way,’ done rather
than completed
⦿ Inaccessible documentation (consider those
using screen readers, or that may not be able
to process audio from a lengthy how-to tutorial
embedded in your documentation
⦿ Outdated or missing troubleshooting
documentation available if something goes
wrong during setup
11

12. Breaking it down further
Missing information
This is the main challenge facing
readers of documentation.
Consider how missing
information gets updated, who is
responsible for doing so, and how
to best convey this information in
a way that makes it accessible to
everyone who may need it.
Jargon
Using jargon and
heavily-detailed terms
without defining them
clearly can frustrate
users.
Structure
Having documentation that
spans different tones and
styles based on who
contributed it can be difficult
for neurodivergent
individuals to parse.
Consider implementing a
style guide for
documentation uniformity.
12

13. Skeletons are our
friends!
Having a rough outline, or a
‘skeleton,’ of what your
documentation structure and
layout should be in its ideal state
helps to not only plan new
documentation, but to refine old
documentation to bring it
up-to-date.
13

14. What does an accessible documentation
skeleton look like?
⦿ Clear header formatting that stays consistent
⦿ Remember the WCAG guidelines: Pause, Stop, Hide
⦿ Install/setup instructions given one at a time (Hint: Use a bulleted
list!)
⦿ Subheadings are labelled and hyperlinked in a table of contents
⦿ Alt text added to images, subtitles and transcripts for A/V content
⦿ Have a glossary if you need one, and remember to keep it current!
14

15. START
WRITING!
Here’s how to tackle what’s next!
15

16. Finally, it’s time to #WriteTheDocs!
16
Define the scope
How long will this project take? Will
outside contributions be accepted? Do
you need to write a style guide, or does
one already exist? How will you work
with cross-platform teams to update
documentation that spans across
multiple departments?
3
Improve and iterate
After your documentation project is
complete, continue to make
improvements to it! Iterate on your
existing documentation to make
changes that will improve the
experience of your users.
1
Get started
Once you’ve scoped your
documentation project, it’s time to start
writing. Ensure that you’re
communicating your progress and
making sure to note any roadblocks
that come up as you’re writing.
2

17. Avoiding scope creep 😱
⦿ Scope creep is, at its core--Getting stuck in the weeds.
⦿ When working cross-collaboratively, don’t be afraid to speak
up when something is approaching scope creep.
⦿ Avoid scope creep by clearly designating who owns updates
and maintenance to particular sections of documentation
before you start to write.
17

18. Drafts, revisions, and publishing
⦿ Drafting documentation collaboratively can be a useful tool for
neurodivergent individuals.
⦿ Using tools such as HackMD.io are also beneficial when
multiple points-of-view need to be considered
⦿ If revising or publishing your documentation is cumbersome,
consider looking into publishing tools such as Docsy or
Docusaurus.
18

19. Making updates
⦿ Make sure to audit your documentation regularly
⌾ Note where updates need to be made, and assign them
to the applicable DRI
⦿ If there is a breaking change on the way, communicate the
change far in advance
⦿ If you see a section of documentation that needs to be
updated, raise a PR or open an issue and assign the relevant
DRI
19

20. What we’ve learned so far
1. Be helpful 2. Avoid jargon 3. Have a skeleton
20
4. Update those docs! 5. Know who owns it 6. Improve and iterate

21. Putting it all into practice!
⦿ This is not only our responsibility, but our opportunity as
documentation authors.
⦿ What have you learned here today that you’ll take back to your
company or open source project to help make your
documentation more accessible and equitable to
neurodivergent individuals?
⦿ How will you encourage new documentation contributions
from neurodivergent individuals moving forwards?
21

22. THANKS!
Have a question? Join me for a Q&A after the
presentation!
You can also find me online:
⦿ Twitter: @kiran_oliver
⦿ GitHub: @celanthe
22

23. CREDITS
Special thanks to all the people who made and released
these awesome resources for free:
⦿ Presentation template by SlidesCarnival
⦿ Photographs by Unsplash
⦿ Circuit background by Hero Patterns
23