Chapter 12

Write for People and Machines

Summary

Your text content doesn’t just appear out of nowhere. It has to be written. This chapter is about writing for the web, understanding how to write for both people and for web services like search engines, voice recognition, accessibility tools, and more.

Does This Apply?

You need content to be written in a way that is understandable by your audiences, so of course this applies.

Narrative

Ernest Hemingway famously said, “There is nothing to writing. All you do is sit down and bleed.”

Let’s make the wild assumption that Hemingway never stared down a 500-page content migration project. He never had to – he was a writer afforded a lot of leeway, whose brilliance came from freedom. He wrote as art, and though it takes looking past his boorish character, he could bleed out some of the most striking and powerful prose.

You are not Hemingway. You are not writing for art. You are working toward something tactical and functional. You are building a website, and, while a bit of levity and creativity is important, you don’t need art. You need something that can communicate effectively.

You don’t get to sit down and bleed; instead, even more importantly, you get to help people understand.

But it’s more than that. The web is limitless, yet fiercely structured. In order for your words to travel, they need to be written for the machines that make the web work: for search engines, voice recognition, and assistive accessibility tools, through use of metadata and in-content structure.

It means writing for people and machines. Hemingway never had to face those odds.

Episode 12: Write for People and Machines (w/ Sarah Winters)

Corey and Deane welcome Sarah Winters, founder of Content Design London and author of Content Design, to the podcast to discuss the difference between content design and content strategy, writing and designing for accessibility, and the work it takes to turn a big ship toward lasting content change.

40:23 | Sarah Winters

Past Episodes

What People Want

The first rule of writing content is understanding that the focus isn’t on writing the words. The focus is on your site visitors reading the words. Reading is, in essence, cypher cracking. Letters, words, and sentences are all codes for illustrative meaning. The more comfortable we are with the code, the faster we are to comprehend.

Comprehension is stifled on the web, where our readers are not necessarily excited or perfectly situated to read what you’ve written, so our goal is to make things as easy as possible. Rachel McAlpine, in her book Write Me a Web Page, Elsie!, lays out the odds we’re up against. Our readers are:

  • Uncomfortable: They’re reading on a bright screen, holding a phone or staring at their laptop.
  • Always adjusting: Because there is no standard width or font size, content layout has difficulty staying consistent.
  • Goal-oriented: There is very little casual reading on the web, especially when you’re selling a product or a solution.
  • Diverse: You can rarely count on a single, universal audience to write for; instead, you are tasked with writing for everyone.
  • Impatient: For all of the reasons above, they don’t want to dawdle around.

In other words, it’s up to us to lighten that cognitive load. It’s up to us to write for people, and not at people.

Writing for Readability: Plain Language and Scannability

To the Center for Plain Language, “plain language” means:

… The target audience can read, understand, and confidently act on the information in your content.

Which means the definition of “plain” is a definition that shifts with the audience. What is plain language for one audience may not be plain language for another audience. Content that is specific to, say, a biology teacher is going to reach a different level of “plainness” than content meant for their students.

First, use shorter, more common words whenever you can, especially if it carries the same meaning, and even more especially if you’re writing content meant for a wide variety of people at different levels of understanding. In a pinch, imagine what your words would sound like if you were saying them out loud during a conversation. Are you “incentivizing your offspring for positive behavior?” Or are you “rewarding your kids for being good?”

Write simply, and your readers will benefit. It’s best to write at a low enough reading level that the widest audience can understand. Without losing meaning, of course. We’re not asking you to “dumb things down.” We’re asking you to be clear and purposeful: write at roughly a high school level; limit paragraphs to roughly eighty words; and avoid jargon when possible.

There are accessibility benefits to all of this: it benefits those with cognitive impairments as well as those who do not speak your language at a high level. It even benefits distracted people. But really, it benefits anyone who is reading it.

Write for Scannability

At our worst, as Ginny Redish puts it in her book Letting Go of the Words, instead of communicating information, we write documents. She says:

Most people come to the web for information, not for a complete document. They don’t want the user manual; they want instructions for the task they are doing. They don’t want the hand-book; they want the answer to specific questions. They want usable, manageable pieces.

This is true even if we look more granular: people don’t want a page – they want an answer on that page. While there are some looking for the full set of instructions, most are simply looking for a detail.

Creating easily scannable content helps you, in essence, break your content page into what might look like proto-pages. Your audience can approach content from any number of angles with a high level of understanding:

  • They can easily parse the different concepts within the page.
  • They can get a feel for the entire process thanks to logical sections within a page.
  • They can quickly find a specific section on a page.
  • They can find unique information based on common formatting clues.

Writing for scannability builds upon the simplicity of plain language:

  • Write short paragraphs and sentences.
  • Write headings that clearly define the section of content.
  • Write one main subject per page, and one main thought or concept per section and heading.
  • Use bullet lists to summarize important points.
  • Make good promises with your links by accurately describing where they will take someone.

Here are examples of low and high readability using the always popular “Star Wars Ipsum”:

Low Readability

High Readability

Writing for Understanding: The Right Thing

If that previous section felt like an exercise in middle-school English, you’re not wrong. The foundation of what we write for the web – just as it is for all writing that’s meant to be read – lies in our ability to be clear and organized.

Writing for the web is not just saying what we mean, but doing it in a way that conveys the meaning. It is writing for both action and emotion.

Voice, Tone, and Editorial Guidelines

Writing is more than just perfect sentences. It’s also voice and tone: it’s the words you choose, and it’s the mood you exhibit. In Nicole Fenton and Kate Kiefer Lee’s book Nicely Said, voice is “what makes people feel like they’re listening to someone they know when they visit your website.”

Let’s define these two terms:

  • Voice: This is who your company In Nicely Said, this is referred to as your company’s public personality; it does not change from day to day. While your organization may have multiple messages or audiences, it should have one consistent voice.
  • Tone: This is the interpretation of your voice in a specific situation. It’s what your readers pick up as they read an error message, or a successful submission of an email address. While your organization will have one consistent voice, it may have multiple unique tones for different situations.

In other words, if your voice is your day-to-day demeanor, your tone is how you sound when you’re mad about the kitty litter box going uncleaned for three days.

Developing voice and tone is purposeful, and requires maintenance. Readers can detect a voice that’s not real. Of course, developing a voice and tone and executing that voice and tone are two different things. Writing with voice and tone in mind can be difficult to non-writers, or writers who feel stifled or micromanaged. It comes down to developing tools that balance the freedom of writing with the strict yoke of editorial standards.

This is where your editorial guideline documentation comes into play. Guideline documentation might take one of many forms, including:

  • Voice and Tone Guide: The focus of a voice and tone guide is around examples and situations, rather than exact terms. Mailchimp’s Content Style Guide has forever been the standard bearer in this department, with good reason.
  • Formal Style Guide: Editorial style guides are staples of the journalism industry, focusing on standards around grammar, usage, and spelling. The web has its own, the Yahoo Style Guide, but be warned that it was written in 2010 and can tend to lag in certain areas.
  • Voice Chart: A voice chart provides a set of “decision-making rules and creative guidance,” in the words of Torrey Podmajersky in Strategic Writing for UX, and focuses on making your user interface content and error messages read a little bit less subjective.

But beyond this, it’s about being patient with writers, fostering an environment of teaching, and reviewing and training throughout the process.

Writing Guidelines for Understanding

Beyond voice and tone – and beyond that approved list of terms you should and can use within your organization or industry – writing for the web is best summed up as “writing for understanding.” Which means the quips we use to add flair to our writing can be troublesome to those who visit our site.

Our goal isn’t to be a stick in the mud or boring. It’s just that there’s a balance between the plain language we mentioned above and the voice and tone we use to infuse brand attributes into our text. Here are some basics we need to understand in order to be both inclusive and honest with site visitors:

  • Be Clear: If you need someone to take action, provide them with a strongly worded task. Instead of “Reach out to us to sign up,” say “Email us at [email protected] to schedule your appointment.” Instead of “Thanks for reaching out!” say “Thanks for contacting our service department! We will contact you within 24 hours to confirm an appointment.”
  • Be Consistent: Stay consistent with tone, direction, and even the words you use to describe things. For example, if your university refers to a specific department by both its department name (Education Department), its school name (The Verynice School of Education), and its location on campus (Verynice Hall), make sure these terms are clearly assigned to specific meanings, otherwise confusion will run rampant.
  • Be Sincere: It’s easy to want to say everything is amazing and wonderful and perfect. It’s probably not. Be honest and sincere with what you write. Review your adjectives to make sure you’re not making some crazy claims. Don’t tell someone your product will change their life. Tell them how your specific features will improve their workflow. Don’t tell someone you’ll get back to them right away. Tell them you’ll contact them within the next 24 hours.
  • Be Jargon-Free: Stay away from jargon, idioms, and metaphors whenever possible – like overusing industry-specific acronyms or technical terms, or dropping nonsense business quips like “being in the driver’s seat” or “taking the bull by the horns.” They’re often more confusing than simply saying what you mean. What’s more, industry jargon draws a clear line between you and any readers not indoctrinated into your circle of knowledge – it says, in essence, that if you don’t know these words, you do not get to enjoy this information. They are difficult to translate, occasionally misinterpreted, and quite often very cheesy.

Writing for Machines

While your content management system focuses heavily on structuring content for more intelligent use, there are still places where your words live in a place of freedom: the rich-text editor, or “WYSIWYG.” In this field you are not tied to fields or content chunks. You can write anything in nearly any format.

But that freedom comes with responsibilities, especially when it comes down to how a machine interprets your content.

First off, let’s remind ourselves that web browsers and assistive tools cannot read. Instead, they scan and parse content based on a set of codes. When we see the words “Mary had a little lamb,” we understand the context within the words. We know that Mary is probably a person. We know that Mary has a lamb, and that the lamb is little. We may even understand some of the background – that this is a line from a children’s song, or that it’s commonly accompanied by a specific melody.

A browser does not know this. A browser sees five words. It sees eighteen characters and four spaces. It may recognize some words based on an internal database – it may understand that Mary is a proper noun (because it’s been told it’s a proper noun) or that a lamb is related to sheep (because it’s been told that “lamb” is related to “sheep”).

Beyond that, though, it knows nothing. We have to tell it what’s important. We have to tell it why it should care.

Headings

Headings are, in essence, section titles. If you’re unfamiliar with how a browser or screen reader encounters content, headings look like nothing more than a design element. This is where trouble sets in; in fact, headings signify to both browsers and readers the topic of a section, in a specific order. They are not a simple design flourish, but instead a framework for understanding.

Just like a page outline, headings are sequential:

  • Heading level 1: This is the top heading. This communicates the overall page topic. Sometimes, this is equivalent to the page title, but even if the page title is separate this first level heading should identify the overall concept of the page.
  • Heading level 2: Second-level headings break the page into major sections.
  • Heading level 3, 4, and beyond: Beyond the second level, headings break larger sections into smaller ideas.

Heading 1, therefore, should be reserved for the title of the page. Search engines use headings to help identify what parts of content are most important. Accessibility tools use headings to allow readers to easily skip sections of the page, approximating the act of scanning a page with our eyes.

Descriptive Text Links: Beyond “Click Here”

Where headings are designed to be scannable and assist with navigation, links are designed to actually take you elsewhere. What this means is that your text links need to be understandable. Again, a link is a promise: you are essentially telling someone that this is where you’re going to go. A “Click Here” link means, effectively, nothing in terms of that promise.

It’s not just humans, either. Search engines use link text to define the destination page. The words you use within a link are the words a search engine uses to understand context – if your link includes the text for “pamplemousse La Croix,” the search engine is going to make the natural assumption that the link itself relates to those words.

Finally, link text serves as a guide for those who cannot see surrounding content. Remember: not everyone or everything can see that context – a “click here” link might mean something if it’s next to a call to action to apply for a loan, but search engines and those who use assistive devices cannot always see that context. They come to a link that says “click here” and they think “Why? Where does this go?”

Instead of “click here” or “read more,” your links should be descriptive and clear. Links on their own as buttons or calls to action should help the user understand where they’ll go, such as a link that says “View our policy catalog.” Links within a larger line of text that are not necessarily calls to action should at least use text that is clear about the target.

Metadata and Titles

The lack of context extends beyond links and into the page itself. Each page requires its own system of machine-readable metadata tags, allowing machines to parse the meaning and structure of the page. This includes:

  • Page title
  • Page description
  • Template-specific content (such as signifying and labeling dates and authors within an article or blog post)
  • Audience-specific content (such as signifying and labeling job posting date within a job listing)

These are sometimes called meta titles and meta descriptions, or they’re created using a scheme called Open Graph (for social media summaries and “cards”), or Schema.org (for more structured content such as media listings or job listings). Regardless, they’re clues to web browsers and search engines and assistive devices as to what content is important … and where it should go.

Summaries and Meta Descriptions

Your content may live in one spot, but it’s going to be found everywhere. Portions of it will be pulled for search engine results pages, or for your on-site news feeds, or excerpted in RSS feeds or social media bots. And while it feels like it might be completely out of your control, how that content is found can often depend on a combination of fields within your CMS and metadata.

What’s important to remember about summary content is that if you don’t explicitly write it, something will write it for you. It’s not enough to just let it truncate where it will – as Karen McGrane often says, “truncation is not a content strate …” – especially if you have the ability to quickly write something that you control. Writing these are as simple as summarizing the purpose and overall thoughts of the page itself, usually within the accepted summary or description parameters.

These fields include:

  • Page summaries/excerpts: Your site may include a field for page summaries or excerpts. These are often used in page aggregations, such as on-site search results or on a news feed, as the small blurb of content under the title.
  • Meta Descriptions: Meta descriptions are most often used in Google search engine results, and allow you to be more purposeful with how your page is encountered when it’s pulled out of its environment.
  • Open Graph: many sites are equipped with unique fields for Open Graph titles, images, and summaries, which allow you to specifically target titles and summaries for use on social media.

Filling in each of these fields for a single page can seem like a pain for your site editors, and we get that. At Blend, we often program a series of fallbacks, so that editors can get as detailed as you like, with the benefit of pre-selected text when it’s less important.

For example, we will build unique fields for page summary, meta description, and Open Graph description. But if you don’t fill out an Open Graph description, that’s okay – we’ll just use the meta description, which is often very similar. If you don’t fill out either, we’ll fall back to your on-site page summary. This way you are populating all of those different fields even if you only have the time or capacity to handle the bare minimum.

Search Engine Optimization

Writing for search engines is a process that feels like running in place. Because search engines change their algorithms constantly, the details of how to write for search engines can be tricky to pin down. There are, in essence, two angles to consider when writing for search engines. One is helping people find what they’re looking for. In this way, writing for search engines is an act of wayfinding that helps users find your content based on the terms they understand. For example, clearly labeling pages, providing helpful descriptions, and providing one-thought-per-paragraph headings will break content up to be findable.

The other is promoting the content you want them to find. In this way, writing for search engines is a kind of marketing, where you’re pushing content toward the words they use in order to gain visibility.

Both are valuable – you need people to find your stuff, and you also want to promote your stuff – and both take a different mindset, just as writing for a user’s manual and writing for a digital marketing campaign take a different mindset.

Chris Corak and Rebekah Baggs, partners at Onward and experts in user-centered SEO, offer a quick list of what’s important in writing for SEO:

  • Find themes within your industry — for example, if a term like “implementation” is often found when people search “content management,” make sure you’re using that common language on your site.
  • Use analytics to understand top-performing and under-performing pages, and develop a plan to rewrite them according to your research.
  • Make sure navigation and organization terms match the words people are searching for.
  • Align structured content (like your meta descriptions and titles) to highlight both your key messaging and important industry keywords.

In large part, if you are honest and truthful in how you position your headings (highlighting the most important content) and structure your page for accessibility (using simple, clear, and accurate link descriptions and headings), you’re also being honest and truthful for search engines. After all, both are technical systems that look for context to help a person understand what’s on a specific page.

Writing for Accessibility

On the web, accessibility is the practice of removing barriers for people with disabilities. Much like new building construction must provide accessible entrances, and businesses must provide reasonable accommodations to employees with disabilities, websites must be created in a way that allow access to information despite any existing or future disability.

Writing for accessibility – much like writing for search engine optimization – boils down to writing clear, scannable, well-structured content. If you’ve done the work for one, you’ve done most of the work for the other. For example, the W3C’s Web Accessibility Initiative includes the following tips for writing for accessibility:

  • Provide informative, unique page titles.
  • Use headings to convey meaning and structure.
  • Write link text in a way that clearly describes the destination.
  • Write meaningful text alternatives for images.
  • Create transcripts and captions for multimedia.
  • Provide clear instructions.
  • Keep content clear and concise.

Simply put, writing for accessibility is just writing for understanding and clarity, with a little bit of structured content thrown in to help assistive devices. Let’s quickly focus on the two we haven’t covered yet: alternative text and multimedia transcripts.

Alternative Text

We’re talking largely about writing content in the body field in this chapter, but we don’t want to discount one of the most important parts of web accessibility: alternative text.

The rule is that every non-text element requires a text alternative so that it can be read (or understood) using assistive services. Your images are essentially invisible to those who cannot see them, and so alternative text (or alt text) helps explain what the image communicates. The basic rule is to convey the same level of information that someone who can see the image might get.

Accessible Media

Videos are just “moving pictures,” which means they require the same level of care as our images. But while images need alternative text, videos (and podcasts or other audible media) need captions or transcripts.

Captions and transcripts aren’t the sole concern of those with permanent or temporary disabilities. Everyone wants captions and transcripts; they are useful for when you might have your computer’s sound down, or because you’re on a bus, or because the text itself is easier to search and index. The main point is that not everyone consumes information in the same way.

To be compliant, you can do one of the following:

  • Captions: Useful when the video is meant to be viewed in real time with the text – a live event, or something in which the video is closely tied to the audio. With captions, you are tying your text directly to the video itself. This means, in addition to the words, you have to consider timestamping and matching that text to the correct spot in the video.
  • Transcripts: With this, the video is no longer the focus: the text is. While this won’t work for live events, or for sound that is closely tied to visuals (such as managing comedic timing), for everything else it provides an easily searchable and scalable alternative to the video itself.

From Words to Design

We’ve talked a lot about content over the past several chapters, and we’ve built a solid foundation based on user goals and expectations. We’ve set a path for action: we’re providing a system by which we can communicate to business goals. We’re really doing some great content things!

That’s all it is, though. Content things. It’s words and images. We have yet to discuss the main visual aspect of the site. We have yet to discuss how content is displayed, how we illustrate the brand beyond text, and how that content responds to different browser widths.

We have a bunch of text files. But we do not yet have any design. And we’ll talk about that in the next chapter.

Inputs and Outputs

Inputs for writing content depend on your organization’s brand standards and guidelines, but at minimum you should have some kind of strategic plan for what you’re going for. You need a site map (so you know what you’re writing and what needs to be created from scratch) and you need a content strategy (so you know the reasons why you’re writing new content).

The output? Brand. New. Site. Content!

The Big Picture

In the perfect project, writing is organized and created throughout the scope of the project, from development of the site map through to launch. In reality, writing often is the bottleneck at the end of a project: not enough time was allocated to making sure all of the new content was created. While we know no project will be perfect, you should aim to be a part of that first group: plan and start writing as early as you are comfortable.

Staffing

You probably need writers. You almost always need writers. If you’re lucky, you already have writers – it’s just that they often do not consider writing as their sole responsibility, despite always seeming to be on hand when you need some content written. As you get closer to launch, however, you may need to hire someone who can either specialize in writing to your brand, or someone who can simply crank out a ton of content while your organization continues with its day-to-day responsibilities.

Resources

Resources

Books

Tools