How a best practice in software documentation helped me be vulnerable and build trust

Image credit: Frank Abgrall

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

Photo by JESHOOTS.com from StockSnap

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

The metaphorical representation of my soul—this grumpy cat.

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

iPhone, ice coffee, Apple MacBook Pro laptop on a desk
iPhone, ice coffee, Apple MacBook Pro laptop on a desk

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.


Ashlee Phillips (that’s me) striking a confident pose on stage at AirBnB as she delivers her talk on web accessibility.
Ashlee Phillips (that’s me) striking a confident pose on stage at AirBnB as she delivers her talk on web accessibility.
Photo credit: Brian Phillips

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…

Ashlee Phillips

Content designer, etc.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store