Documenting
Documentation is critical to the health, maintenance, and longevity of digital systems. As a systems writer, I've written content about the system as well as for the system.
I've found that Writing, Design, and Accessibility systems often intertwine. Writing design system component documentation cannot be separate from the content strategy that makes the component understandable (which is the third WCAG principle).
Design System Documentation
Airbnb Design System
The design system hadn't had a redesign in a few years and it was starting to show. Launch teams were designing their own custom components because the components in the system weren't flexible or innovative enough. Our CEO even took the stage at Config and said design systems limit innovation. Our mission: redesign the system website and documentation, design flexibility into our existing components, and add new components into the system.​
Documentation redesign
We needed a new look and feel for our component articles. I got the team started by architecting a low-fidelity wireframe in Figma that highlighted the content strategy for each article. I collaborated with a few System designers to make sure all our bases were covered, then they designed the documentation templates from there. Once we started adding content to the templates, we made a few more adjustments, then landed on the final templates.​
Edit and review with one voice
The documentation was written by multiple authors, yet we wanted it all to sound consistent, like one voice. I reviewed and edited every article to ensure that our documentation had the right length, level of technicality and detail, voice and tone, and proper grammar and punctuation. My review was a documented stage of the project.
Content strategy and governance
I created a Design System style guide and content governance plan to help the team keep the documentation fresh over time, even with multiple content creators. ​
​
The System writing style guide was different from the larger Airbnb Writing Style Guide (more on this below), and was focused on supporting designers who might be writing content, as well as writers who might be working with the team in the future.
​
The style guide covers writing principles, accessible writing guidelines, a terms glossary, and how to write new documentation articles. It's a living document because the design system discipline at Airbnb is fast-moving, flexible, and dynamic. The style guide flexes with the system.
Accessible Writing Style Guides
US Bank, Twitter, and Airbnb Style Guides
As a systems and accessibility UX writer, much of my work includes writing foundational content for design, writing, and accessibility systems. While the systems are often separate (Design System, Writing Style Guide), they all intersect.
​
For example, in my role as an accessibility consultant at US Bank, I worked closely with the Content team to craft a set of accessible emoji use guidelines. Using a sparkling unicorn emoji is okay, but only once in the message, and it must be at either the beginning or end of a sentence. I applied the WCAG Cognitive and Learning Disabilities recommendations to ground the guidelines in global expectations.
​
Accessibility writing guidelines
I believe in making accessibility part of ​system guidance instead of a separate set of guidelines. Design systems should be accessible. Writing systems should be accessible. That way everything you design and write is (ideally) born accessible.
Throughout my roles I've taken the existing writing style guide and infused it with accessibility best practices. Sometimes an accessibility section needs to be added to a content entry, and other times the guidance just needs to be updated to be accessible. For example, how to annotate icon buttons can be a separate section in the "Buttons and CTAs" entry, whereas guidance to use sentence case instead of title case can be added in the general documentation.​
Accessibility writing guides
In addition to ensuring the foundational documentation includes accessibility best practices, I create topic-specific guides that go deeper. Three topics that require more than a paragraph in a style guide are:​ image and video description best practices, accessible language, and accessibility specifications.
Image and video description best practices
Writing great image descriptions (also known as alt text) is an art that takes practice. The guide I've created defines the types of images the company encounters, guidance on how to write great descriptions, and lots of examples.
​
Recently, I've found myself writing prompt guidance for AI-generating image description LLMs.
Accessible language
Writing appropriately and respectfully about disability and accessibility does not necessarily come naturally. Words and phrases that seem appropriate are not. And those that seem inappropriate actually aren't. The best way to know for sure is to have an accessible language guide that's informed by people with lived experience of disability, and organizations run by, and for, disabled people.
​
An accessible language guide, like all accessibility guides, should be a living document. It needs to be regularly updated because, like all language, things change, and writing teams need to adapt quickly.
Accessibility specifications
Accessibility specs for short, these are annotations in Figma design files that tell engineers how to code content. Designers and writers are empowered and educated to create these specs themselves, but consulting with a member of the Digital Accessibility team is the best way to ensure accuracy and consistency across the platform. I work with my fellow UX writers, designers, and engineers to create correct content accessibility specs.
