Write the Docs: Writing Documentation with Neurodivergent Open Source Contributors In Mind – Rin Oliver

This Write the Docs Portland talk was given by Rin Oliver. Rin is a technical community builder at Kamundo. Rin is multiply neurodivergent – they are autistic, have dyspraxia, dyscalculia and ADD. They have been involved in open source software (OSS) since about 2015 in one way or another. They have been both a maintainer and contributor to documentation. They are an advocate for improving the OSS contributor experience for neurodivergent individuals, which is what this talk was about. 

“Neurodiversity is the diversity of human minds, the infinite variation in neurocognitive functioning within our species” – Dr. Nick Walker

Why we need neurodivergent practices

First, Rin summarized reasons why we should focus on neurodivergence in our documentation. 

If you don’t have equitable and accessible documentation best practices, you’re going to miss out on contributions from neurodivergent individuals.

But getting started with writing neurodivergent docs is not easy. 

"Open source is hard to get into. As the 'hows' are not very clear, and neurodivergent people may not understand the process that easily" – Smashing Magazine

Although it's a challenge, there are specific things you can do to be neurodivergent in docs. 

How to be neurodivergent in docs

Rin outlined some guidelines to follow when appealing to neurodivergent individuals with your documentation. 

Invest in localization

Localization efforts are crucial to your success. If someone requests to translate your documentation, have a section in your contributor guide dedicated to localization efforts, how to get started, and best practices for docs localization teams. 

Avoid jargon

Next, 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. Surface it on your site and link to the glossary whenever a term is used that one may not be familiar with. 

Use positive language

Use positive language that encourages users and contributors – don’t talk down to your users. This can include:

• Thanking people for their contributions
• Encouraging them when they submit code for review
• Being compassionate and understanding rather than nitpicking

Set clear expectations

Set clear expectations of what documentation pull requests should look like. Use templates for new pull requests and issues to make sure they adhere to your established style guide. 

Have a Directly Responsible Individual

Have a Directly Responsible Individual (DRI) that people can approach if they have questions about the products or docs. Know who owns updating particular sections of documentation. 

Use step-by-step instructions

Give environment setup or demo steps one at a time in the docs, so people can clearly say “I got stuck on step 7” rather than have to wade through a paragraph of instructions. Clearly state which sections of your documentation are accepting pull requests, if any. Make it clear when you’re not accepting outside pull requests. 

These recommendations are helpful for anyone using your open source documentation, and well worth taking the time to invest in. 

What not to do

Rin also had some suggestions for what not to do with your documentation.

Don’t reject documentation improvements that got something “most of the way” done, rather than completed. Consider those who are using screen readers or that may not be able to process audio from a lengthy how-to tutorial embedded in your documentation. 

Missing information is the main challenge facing readers of the documentation. Consider how information gets updated, who is responsible for doing so, and how best to convey this information in a way that makes it accessible to everyone who may need it. 

Don't use jargon and heavily detailed terms without defining them, as this can users.

More ways to be neurodivergent in your docs

Rin has even more recommendations for how to be neurodivergent in your documentation. These are helpful both for your documentation team and any other contributors:

• Consider having a style guide for your documentation, so your documentation doesn’t span different tones and styles based on who contributed. Parsing these variations in tone and style can be difficult for neurodivergent individuals. 
• Having a rough outline of how your documentation structure and layouts should be in its ideal state helps plan new documentation. Keep it clear and consistent, with clear header formatting. Use bulleted lists to write your install/setup instructions. 
• Add alt text to images and subtitles and transcripts for A/V content. 
• Have a glossary and keep it current. 
• When you start writing, define your scope for how long the project is going to take and whether you’re going to take on outside contributions. How are you going to work with teams that aren’t yours? How will you work with the marketing and engineering teams? 
• When your documentation process is complete, you can improve and iterate on it. It shouldn’t be a static object that never changes. 
• Scope creep can be a problem in documentation. When working cross-collaboratively, don’t be afraid to speak up when something is approaching scope creep. Clearly designate who owns updates and maintenance of particular sections of documentation before you start to write. 
• Drafting documentation collaboratively can be a useful tool for neurodivergent individuals. If revising or publishing your docs is cumbersome, look into publishing tools such as Docsy or Docusaurus. It doesn’t have to be a painful process if you use the right tools.

That's how to make your documentation process more accessible. 

Final remarks

Rin also suggested auditing your documentation regularly and note where changes need to be made, then assigning them to the appropriate DRI. If you need to make big changes, communicate this far in advance. If you see a section of docs that needs to be updated, raise a pull request or open an issue and assign the relevant DRI. 

It’s not just a responsibility as documentation practitioners, but our opportunity to make the OSS experience better for neurodivergent individuals.

Watch the full talk here.