Writing For Everyone

Hi

• I'm Katy DeCorah
• I work at Mapbox
• Why people sometimes listen to me

Why This Talk

• Why this talk?
• Have you ever read a book, but couldn't get through the first chapter. Perhaps the author has a strong vocabulary or your couldn't follow the story. Maybe you tried to get through it, but unless it was compulsory you probably gave up because if this *first chapter* is tough then the rest of the book will be too.
• Writing has that effect, whether it's a tutorial, a tweet, a blog post, or a README - it's all the same. If you box out users with thick jargon or indirect language then they'll be afraid of your tools, API, or your blog.
• We write and document, to share
• To me, clear writing is welcoming.
• It's using plain language and active voice to make sure your audience can follow along.

And Hard

• This talk aims to help make it less so.
• this talk assumes that you know your audience and subject

Writing Checklist

• Uhh whoops.

Title Words To Avoid

• Explain that it's easy.

Title2

• Explain it directly.

Before

• You can easily add Mapbox.js to your page just by adding the JS and CSS in the head.
• Easy for who?
• Just put it where?
• Sometimes we'll want to say that something easy to assure the user

For Who

• but if it's not easy to them then they'll feel dumb.

After

• You can add Mapbox.js by copying the following lines into the head of your page.

Your Job

• It's not your job to tell someone you don't know that what you know is "easy".
• It's your job to explain it in a way that will leave that person feeling confident.

Let Them

• Hopefully the instruction worked and they'll say it's easy.

Words To Avoid

• These words can change the tone of your writing.
• Remember, it's all about context.
• If you're unsure, try removing a word from your sentence. If the sentence is still strong, you're good. If not, then leave it in.

Title Plain Language

• Use plain language.

Title2

• Use plain language.

Close Your Eyes

• Let's try an exercise.
• Please relax. Close your eyes, if you'd like.

Before

• As you inhale activate your diaphragm, the muscle located horizontally between the chest cavity and stomach cavity, by contracting it.

What

• There's got to be an easier way to say this.
• Try this...

After

• Breath with your stomach.
• Was the original instruction more accurate? Sure. Plus, we learned a lot about the diaphragm. But I only really wanted you to breathe deeply. There's not going to be an anatomy quiz later.
• While this instruction made you think less and you performed the same task!

Relatable

• Making something relatable will often make it memorable.
• Using common words is a benefit.
• Diaphragm vs stomach

Concise

• You don't have to tell them everything all the time. If you want to learn more about deep breathing, I'm sure you can go off on your own adventure.
• Or I could be helpful and link to more information.
• Plain language can help make you boil down what you're really trying to say or have accomplished.

No Dictionaries

• Are you teaching them to use your API or study for the SATs?
• Plain language will help you focus on the important stuff instead of flowery language.
• If you can't avoid jargon or difficult words, link to them, create a glossary

Try This

• Here are a few more words and some alternatives.

Title Active Voice

• write in active voice.

Title2

• write in active voice.

Before

• after the file is downloaded

What

• Who or what is downloading the file?
• Did I miss something?
• Should I reread the last paragraph or should I look ahead?
• This sentence is in passive voice and it's hard to tell who need to download this file.

After

• After you download the file.
• Ok - the action is on me.
• With active voice someone is directly acting out the verb.

Direct

• With active voice there's no question as to who is doing what.
• It also holds people accountable.
• There are circumstances when passive voice works better, but instructions should almost always be in active voice.

Relatable

• Humans relate to other humans. When you put "you", "I", or a pronoun in front of an action - it's relatable.
• Users can immediately see that this is an action that they can do.
• They don't have to think about it.

Tell Em

• If the user has to do something
• Tell them.
• Need help writing instructions? Check out recipes.

Title Organize

• Use headlines to chunk ideas into sections. This will help the chronic skimmers find what they're looking for, it also help others get the bigger picture.

Title2

Lists

• these instructions are not easy to digest
• Use lists to emphases steps or points.
• An ordered list will tell the user "ok, time to follow along"

Tables

• Use tables to visually organize information.

Headlines

• Headlines add context
• Makes content skimmable

Title Peer Review

• get a peer review

Title2

• get a peer review

Before

• A real sentence I wrote a few weeks ago
• We adapted many of these demos have from Mapbox.js examples.

Fresh Eyes

• I swear I proofread.

After

• Until I had someone else read and fine the extra word.
• At Mapbox, we make it part of our workflow to have at least an extra set of eyes on anything we push out.
• It helps catch things, big or small.
• It has always opened us up to learning different writing styles.

Tools

• Sometimes you don't have someone around.
• These online tools are great.
• Copy and paste your text and it will analyze.

Checklist

• Here's the checklist agin.
• It's using direct, plain language, in active voice.
• It's been peer reviewed and organized into a list.
• This list can help improve your writing.
• But it's not just writing, it's building a relationship with your users through clear and direct writing.
• write something that you'd like to read
• anticipate questions and scenarios
• And maybe it's your clear writing that helped someone understand and learn JavaScript for the first time all while using your tools.

Thanks

Tools