Documentation is only useful if people can read it, so it stands to reason that it needs to be accessible. But what about making it inclusive? What does that entail? How can we make sure that everyone is benefitting fully from our documentation AND feeling as though they are the intended audience? Open source projects especially can sometimes make people feel as though they don’t belong - don’t lose your audience because you didn’t think through your writing carefully!


In this session, we’ll discuss how to make sure your documentation can be read and understood by everyone. We’ll talk about strategies to make your writing as clear as possible, which can be difficult when using big technical terms and complex ideas. Have you ever thought about what NOT to say in your documentation - what can be off-putting and make people feel excluded? That’s an important aspect, but one that’s often overlooked, so we’ll go over some things to watch out for. Formatting, layout, and accessibility are also important, so we’ll review some best practices. We’ll also cover some content strategy - making sure your users and readers have access to all of the information they need requires some planning. 


At the end of this session, you will come away with an actionable list of items and fixes to apply to your documentation.


Presentation Materials

Attachment Size
Writing Inclusive Documentation.pdf 4.33 MB


Track Audience(s) Experience Level Tags
Content Managers, Editors
Developers (Back-end php focused)
Developers (Front-end focused)
Developers (Javascript focused)
DevOps Engineers, Tech Leads, Lead Developers
Project Managers, Producers, & Product Owners
All / Any

Scheduling Information

1:00pm - 1:50pm
, A11y, Performance

About the Presenter

Alanna Burke

Documentation, Training, and Developer Advocate

After ten years as a back-end developer, Alanna decided a change was in order. Still carrying a torch for Drupal, content management systems, and helping others, she is now working as a documentation writer, trainer, and developer advocate at Alanna also serves as a track chair for DrupalCon North America, and is on the leadership team of Drupal Diversity and Inclusion. The proud owner of many pets, including seven guinea pigs, she is also very involved in animal rescue.

Connect & Follow

Session Recording

This Session's Recording