Writing For Everyone
- 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.
- This talk aims to help make it less so.
- this talk assumes that you know your audience and subject
Title Words To Avoid
- 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
- but if it's not easy to them then they'll feel dumb.
- You can add Mapbox.js by copying the following lines into the head of your page.
- 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.
- 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
Close Your Eyes
- Let's try an exercise.
- Please relax. Close your eyes, if you'd like.
- As you inhale activate your diaphragm, the muscle located horizontally between the chest cavity and stomach cavity, by contracting it.
- There's got to be an easier way to say this.
- Try this...
- 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!
- Making something relatable will often make it memorable.
- Using common words is a benefit.
- Diaphragm vs stomach
- 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.
- 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
- Here are a few more words and some alternatives.
Title Active Voice
- after the file is downloaded
- 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 you download the file.
- Ok - the action is on me.
- With active voice someone is directly acting out the verb.
- 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.
- 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.
- If the user has to do something
- Tell them.
- Need help writing instructions? Check out recipes.
- 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.
- 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"
- Use tables to visually organize information.
- Headlines add context
- Makes content skimmable
Title Peer Review
- A real sentence I wrote a few weeks ago
- We adapted many of these demos have from Mapbox.js examples.
- 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.
- Sometimes you don't have someone around.
- These online tools are great.
- Copy and paste your text and it will analyze.
- 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