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.
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 |
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
|
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:
|
||||||||||||
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 startedTo 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 mapTo 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: