How a best practice in software documentation helped me be vulnerable and build trust
When I joined my team in 2020, I had not stepped foot in the office let alone met a co-worker in real life. I was having a difficult time feeling connected, reading people, and opening up. Vulnerability and transparency are major aspects of collaboration, so when there’s something in the way, like screens, the working relationships and the work suffer.
Enter: README.
Generally used for software documentation, README files introduce and explain a project. It helps people understand what’s going on under the hood, so to speak.
Simple, straightforward and tech-oriented (perfect for my engineer cohort), README seemed like the…
Prompts courtesy of the Daily UX Writing Challenge
Originally posted as a Medium Series on September 10, 2019
Day 1
Scenario
A traveler is in an airport waiting for the last leg of a flight home when their flight is canceled due to a severe storm at their destination.
Challenge
How does her airline app tell her this and what does it say?
Parameters
Headline: 45 characters max
Body: 175 characters max
Button(s): 25 characters max
Solution
16 “best practices” I hate
I collect pet peeves. And none bother me more than questionable UX writing.
Every time I come across bad product copy or misleading advice, I add it to my collection. Each one proves how vital and subjective writing is. (And why it should be left to the professionals.)
To borrow a warning from Dante, “Abandon hope all ye who enter here.”
Let’s dive in.
Useless words
Retry
Even as a 5-character word, I can’t make sense of “retry.” Half the time, I mispronounce it like “retrie,” and the rest of the time, I want to punch it.
I would never in my life…
Hard-won wisdom from the product trenches
Though in its infancy, UX writing has been thoroughly vetted. Hundreds of articles cover what it is, how to do it, and why it matters.
And I consumed them like a box of Thin Mints: one by one until I had a throbbing headache.
Now that I have some experience under my belt, I have a few tricks of my own.
One: Add [a curse word] to the end of your content
A gut check rather than a red flag, the curse word tactic helps me judge tone and delivery.
Trust me. Tack “bitch,” “ass,” “douche bag” (or any word that’d cost a quarter to the swear jar), and see how…
It’s easier than you might think
Words are fundamental to communication — on and off the web. And because a significant component of digital accessibility is about making all content available as text, writers have one of the most substantial impacts on creating accessible experiences.
Basics
We’ve all experienced frustrating — or even debilitating — experiences online and with our devices. Your users don’t consume content in a vacuum. They made it to your website from different generations, cultures, and browsers: don’t let your perspective get in their way.
As you write, consider the following:
- Would this make sense to someone who doesn’t work here?
- Could someone…
An easy-to-follow guide to AA compliant content
Written content
Avoid referring to content by sensory characteristics:
- Shape
- Size
- Screen location
- Orientation
- Sound
- Color
Label form fields.
Structure and formatting
Write headings and labels that explain or describe the content that follows.
Navigation
Provide copy for webpage titles.
Use consistent terms on navigation-related buttons and links.
Write descriptive link text.
Specify the current step in a sequence (aka breadcrumbs).
Images
Provide appropriate null, short, or long alt text.
Use icons — and their alt text — consistently.
Provide transcripts/captions for video and audio content.
This is a transcript of a talk I gave at the Content Strategy SF Bay Area Meetup at Airbnb.
The power of the Web is in its universality. Access by everyone, regardless of disability, is an essential aspect.
This is a quote from Tim Berners-Lee, the inventor of the Web. His vision is both accessible and inclusive. Everyone — no matter their language, location, ability, or device — should be able to use the Web.
In my experience, we discuss how to add accessibility features after the fact. How can we go back and incorporate accessibility? What we’re really asking…
A hotbed of inspiration, education, and obsession
Articles and how-tos
2021
Accessibility
- 3C of interface design: color, contrast, content
- 7 guidelines for writing accessible microcopy
- Accessibility for teams
- Accessible design: how to make this world a better place for all
- Adding alt text descriptions
- Better link labels: 4Ss for encouraging clicks
- The business case for digital accessibility
- Content strategy 101: accessibility
- Disability, language, and service design
- Empathize by exercise with accessibility
- Getting to the heart of digital accessibility
- Human computer interaction for the visually impaired
- How tables can make content less accessible
- How to…
Ashlee Phillips
Content designer, etc.
