Wordsmith

How We Write: Inclusive Content is Content for ALL

~ Susan Kelley ~ Leave a comment

At a company I worked for a few years ago, I first heard about the concept of “the golden thread.” Essentially, the “golden thread” is a metaphor for the decisions, behaviors, and processes that provide the connection between strategy and actual results. It’s interesting to think that the objective could be something like “to improve the environment” and that there is a thread that could guide you along that path. Or an objective like “to own a home in my city” knowing that, sure enough, if you follow the thread one day you will hold the keys to your own front door.

For a technical writer, the notion of a golden thread should be much more than just a content thread. We employ those all the time. A document that outlines a process, from start to finish, should have a thread running through it. A Standard Operating Procedure manual should have an easily identifiable thread to follow from one process to another, weaving through an entire organization. The metaphor is not difficult to picture.

Although easy to spot in some instances, the notion of a thread tying together so much that it leaves no one out is more elusive. And yet, it is essential in today’s communication.

As a content strategist, I try to be mindful of all of the aspects of inclusivity as I write and design. My audience can vary from newcomers to the product I write for to highly experienced users. I write to the needs of engineers and data scientists, but also new adopters and first-time visitors. But experience level is not the only area where I must think of inclusion. That part is actually the easier lift.

Where inclusivity matters in technical content is in writing in a way that every reader can understand. In best-case scenarios, someone has come before and prepared a thorough style guide that captures clear writing, because writing clearly is more than minimalism. Cutting away formal words when less formal ones will do is one step in the process. I choose to write “let” rather than “enable” – as in “this product lets you plan your wedding” instead of “XYZ software enables you to plan a wedding.” Right?

Erwin Steinberg of Carnegie Mellon University was the first scholar to champion what he called “plain English.” Casting aside passive voice and professional jargon, Steinberg argued that writing simply and plainly was the best approach to complex concepts. His thought prevails today, especially when writing inclusively.

Today, many readers are approaching documentation with some accessibility issue. From low-vision to color blindness to dyslexia, the number of reader-centered accommodations is vast. One would think it would be impossible to consider all of them. And one would be wrong. By choosing to write pages that do not have complex markup that a screen reader wouldn’t understand, you have chosen inclusive writing. By using proper and bold headings, you allow those with low vision or attention deficits to more easily scan and identify chunks of information. Including images only with a corresponding text description assists a wide variety of readers and adds to easy clarity with little effort on the writer’s part.

It’s important, as a content designer, to consistently test and modify documents. There’s no such thing as the perfect, complete document. (Remember, perfect is the enemy of done.) Knowing this, though, it’s equally important to revisit your writing and your language choices as regularly as possible to see where you can improve. Scheduling regular reviews of your own work is the best way to see where you missed and where you didn’t.

When creating content of any kind, keep a few numbers in mind:

  • 26% of the US population has a disability
  • 20% has a mental illness
  • 5% is LGBTQ+

So what does this mean for writing? Glad you asked.

  • Monitor cultural references that not everyone will understand
  • Use preferred pronouns when writing personally, neutral pronouns whenever possible
  • Don’t assume that readers are heterosexual, male, female, young, etc.
  • Use gender-neutral professions and titles (e.g. firefighter, not fireman)
  • Never assign a gender to a quality (that is, strong is not manly and feminine is just off-limits)
  • Add detailed descriptions for links, not just “click here”
  • Never use ableist language (lame, blind, dumb)
  • Don’t swap out mental health assignations for daily emotions (someone who is meticulous is not OCD)

Along with these practices, keep in mind that shorter is better, jargon is awful, and if you have to use some fancy words you should build a glossary. Never rely on a stereotype and don’t assume a joke is funny to everyone. Absolutely choose welcoming topics, consider readers’ needs, and look for ways to improve every day.

When all is said and done, if you aren’t sure – ask. Rarely do people who are asked for their input respond poorly. People who are not considered or included – now they can get a bit (justifiably) upset.

Write on.

Advertisement

#Ilooklikeatechwriter

~ Susan Kelley ~ 3 Comments

 

International-Womens-DayI know I just posted yesterday, but I have had a working draft of this piece in the hopper for a while; it just never quite grew its feet, as I like to say. And I can’t put a piece on the blog until it has its own feet. But today, being Women’s Day and all, the piece found its feet.

I recalled Isis Anchalee – remember her? She’s the bright, talented, strong, and yes, beautiful platform engineer from the Tech Startup OneLogin who asked her to participate in their ad campaign, which then sparked the #ilooklikeanengineer hashtag movement. It didn’t take long for the misogynists among us to determine that Isis was simply too pretty to be a “real” platform engineer. There’s just no way a smart brain could be housed in that attractive body.

The movement caught on fast, but it has faded just as quickly. It’s not enough to repeatedly have lists like Forbes top 30 women under 30, although that’s a great list. I say it’s not enough, because when a company like Microsoft reveals its diversity numbers to reflect the staggeringly awful truth: over 75% male and 60% white, with an only 29% female workforce globally, that’s alarming. And then comes the real hit: only 12.5% of Microsoft’s senior leadership in America is female. (Source: Forbes). This is happening even though we know that women are generally better at coding tasks than men.

But we also have to reveal the truth that, according to the US Department of Labor, only 12% of Computer Science graduates today are women.

Why? What about this environment is blocking women? Are we really just not cut out for this field?

ways-to-celebrate-international-womens-day-online

Not really. According to Gayle Laakman McDowell, author of Cracking the Interview, and a coder herself, it’s primarily that girls, when they are girls, are mostly sent the message that, “hey, this stuff is not for you.” Subtly or overtly, young women are, from a very young age, steered toward the humanities while young men are steered toward hard sciences. (We’ve known this for a long time, but I’m providing ethos here. I’m a writer, so to show you I have backup, I provide a subject-matter-expert, okay?)

So we tell girls and young women that they just don’t look like coders. They look like teachers, they look like nurses, they look like bank tellers or whatever, but they do not look like they fit in the cubicle-hive style pressure system that is software development or platform engineering. Is that it?

In other areas of their lives, we are telling them to be “totally natural,” or to be proud of what they look like. We tell them to embrace their body types and to live their lives with gusto. Kate Winslett recently signed a modeling deal with L’Oreal that has a “no Photoshop” clause, and we applaud this honesty and truth to herself.

But we haven’t told young girls that if their true beauty is in writing code, that they are totally entitled to that gorgeousness?

The percentage of women who work in tech companies remains consistent, at around 30%. So there ARE women who do this stuff, but it’s stagnant. It is failing to grow. Even though more women go to college, and an even greater number of women attain graduate degrees, the percentage stays flat. Now, what I find truly remarkable is that the percentage of women in technical or leadership roles – roles where they can actually influence the direction the company takes, is even lower. This difficulty may be the result of well-known sexism in the technology sector, or at least an unwillingness to combat it. The New York Times ran a great piece in April of 2014 called “Technology’s Man Problem,” documenting just this trend, and not much has changed in the last two years, but some things have.

It is not just a matter of moving more girls into a pipeline of studying STEM, because the high rate of attrition in tech moves them right on out the door just as quickly. Teaching women and girls that the tech field is appealing, lucrative, and open to them is not the quick fix we hoped it would be. Instead, fixing the culture that says, “you don’t look like an engineer, coder, tech writer…” THAT is the solution, or at least part of it. In the UK, a campaign called “This Girl Can” strives to connect young women through physical activity and inspiration, while here in the US, Target recently launched an ad campaign called Target Loves Every Body.

I believe we need a culture shift that defines, or redefines, the landscape to show that coders look like lots of things, and writers look like lots of things. Women in many careers have been trying to reshape their images from Hollywood to magazine covers, so why not in Silicon Valley, too?

Women helping women is the key to confidence and the key to success. If tech culture is going to change, everyone needs to change. The emotional and professional cost is simply too high not to. So on this, Women’s Day, the challenge is to reach out to a woman in your field – or a woman not yet in your field – and mentor or inspire, encourage or reassure her. That is how it gets done. Make a pledge to yourself that you will make room in tech for one more young woman, or that you will make additional room for one more established woman. It’s a jungle in here. Even women who have worked in here for years can get lost in the tangle of tasks, so have lunch this week, next, and next month too. There is networking to be done, and we could all use it. Today does not need to be the only Woman’s Day you have this year. Let the women in your life, especially in your tech life, know that they LOOK like accomplishers, achievers, builders, and leaders.

And then, if you are a woman, make sure you accomplish, achieve, build, and lead.

iwd-women

Can Software Write This Better than Me?

~ Susan Kelley ~ 2 Comments

In my job, Icomputer writer’m expected to use a variety of tools to ensure accuracy, word count, compliance, style – adherence to a host of things that keep me “in line” with the company’s overall design and standards. This causes me to wonder: as part of a team of software developers, could my team design software that automates the process of writing the documentation for their own software with enough accuracy that the documentation specialist goes the way of the dinosaur?

I mean, the whole point of some of my products is to automate processes that human beings used to perform, and to automate them to such a degree of precision that people are hardly required to be cognizant, let alone present, for the actions these programs perform. We’ve designed such reliable systems that banking, health care, military information and community design can count on big data to gather and maintain the necessary materials to run our daily lives, and to store that data, to anticipate problems before the occur, and to rectify those problems with limited human intervention.

When you think, “but this type of automation cannot be applied to writing…writing requires critical thinking and analysis!” You would be correct. But you would be overlooking tools like the lexical analyzer Wordsmith, and the automated writing tool also named Wordsmith. Created by Automated Insights, Wordsmith is the API responsible for turning structured data into prose – it literally takes baseline information and makes an article. Could I be out of a job?

Feed me some data, and I write articles, too, only you have to pay me and occasionally socialize with me. Not so for Wordsmith.

The freakish thing about Wordsmith is its accuracy. I’ve studied a good bit about semantic language interpretation, and in my graduate program at Carnegie Mellon University, I dabbled in software interpretation of language, working with a pretty notable team on designing huge dictionaries of strings of language. The thing is, computers are great at reading – they can read at much faster rates than humans, they can digest huge chunks of information and store that information at infinitely larger capacities than the human brain can and their recall is spectacular. Skeptical? Just watch the amazing Jeopardy matches between IBM’s Watson and you’ll soon see that computing power can be harnessed to cull through the informational equivalent of roughly one million books per second. Humans just can’t keep up. Humans who write can’t touch that.

If computers learn a perfect formula for the Great American Novel, we are doomed.

Something to consider. Let’s try to keep this a secret from my bosses, shall we? My team of very excellent software developers may decide that this is a project worth undertaking, and the next thing you know, it won’t be just data that Wordsmith will be analyzing.

In the meantime, I will rely on the human eye and the need for context clues and interpretation that Wordsmith and Watson lack. I’ll count on the systems of reliability and emotion. I’ll count on what I know. What I learned in that high-functioning graduate analysis: A computer cannot tell the significant difference between these two exchanges:

Scene 1: A funeral home. A somber affair, all is quiet. A man says to a woman:

“Sorry for your loss.”

The appropriate response? She shakes his hand and nods, quietly.

Scene 2: A soccer game. A sunny afternoon. The breeze is blowing gently.

A boy says to a girl:

“Sorry for your loss.”

The appropriate response? She high-fives him and replies, “No sweat! Let’s grab some pizza! Woooo hooo!” As they tumble into a minivan, shouting jubilantly, kicking off their shoes.

No computer can decipher the differences in – “Sorry for your loss.”

Sorry, Wordsmith.

I’m going out for pizza.