Writing for everyone.

Hi! I’m Katy DeCorah.

I’m an explainer, helper, and tinkerer at Mapbox.

Clear writing is welcoming.

Clear writing is hard.

Writing checklist

  1. Explain that it’s easy.
  2. Utilize plain language.
  3. Have it written in active voice.
  4. Organize content with paragraphs.
  5. Get a pear review.

1. Explain that it’s easy.

1. Explain that it's easy it directly.

before

You can easily add Mapbox.js to your page just by adding the JS and CSS in the head.

What if it’s not easy?

after

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

Don’t tell them it’s easy, show them.

Let them say it’s easy.

More words to avoid:

Find more: https://css-tricks.com/words-avoid-educational-writing/

2. Utilize plain language.

2. Utilize Use plain language.

Let’s try a deep breathing exercise.

before

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

Uh. What?

after

Breathe with your stomach.

Plain language can make your text relatable.

Plain language can make your text concise.

Don’t make them reach for the dictionary.

Instead of Try this
utilize use
in order to to
implement start

www.plainlanguage.gov

3. Have it written in active voice.

3. Have it written Write in active voice.

before

After the file is downloaded

Uh. What?

after

After you download the file…

Active voice makes your text direct.

Active voice makes your text relatable.

If the user has to do something, tell them.

4. Organize content with paragraphs.

4. Organize content with paragraphs lists, tables, and headlines.

before Click Fonts from Studio’s toolbar. Scroll down until you find “Mark Offc Pro” and click on it to see its weights and styles. Replace each font variable value with the new font name. Click Save to see your styles changes. after
  1. Click Fonts from Studio’s toolbar.
  2. Scroll down until you find “Mark Offc Pro” and click on it to see its weights and styles.
  3. Replace each font variable value with the new font name.
  4. Click Save to see your styles changes.
before Mapbox Studio supports the following languages: localized (name), English (name_en), French (name_fr), Spanish (name_es), and German (name_de). after

Mapbox Studio supports the following languages:


Language Value
localized name
English name_en
French name_fr
Spanish name_es
German name_de
before

This guide walks you through examples in the Google Maps API v3 and then shows you how to do it in Mapbox.js.

To start, you’ll need the latest version of Mapbox.js and CSS. You can link directly to the Mapbox hosted versions by copying this snippet into the head of your HTML document.

You’ll also need to set an access token. Reference your access token by adding this snippet of code to your HTML.

In each of the examples below, we’ll show you how Google does it and then we’ll show you how it’s done with Mapbox.

To add a web map to a page, you need to initialize it first.

Mapbox initializes a map with L.mapbox.map.

after

This guide walks you through examples in the Google Maps API v3 and then shows you how to do it in Mapbox.js.

Getting started

To start, you’ll need the latest version of Mapbox.js and CSS. You can link directly to the Mapbox hosted versions by copying this snippet into the head of your HTML document.

You’ll also need to set an access token. Reference your access token by adding this snippet of code to your HTML.

In each of the examples below, we’ll show you how Google does it and then we’ll show you how it’s done with Mapbox.

Initializing a map

To add a web map to a page, you need to initialize it first.

Mapbox initializes a map with L.mapbox.map.

5. Get a pear review.

5. Get a pear peer review.

before

We adapted many of these demos have from Mapbox.js examples.

Everything looks the same.

after

We adapted many of these demos from Mapbox.js examples.

Nobody around? Try these:

Writing checklist

  1. Explain it directly.
  2. Use plain language.
  3. Write in active voice.
  4. Organize content with lists, tables, and headlines.
  5. Get a peer review.

Thanks for listening!

How are you writing?

@katydecorah

katydecorah.com/writing-for-everyone

Sites + articles

Books