How I write
This is a devlog I wrote at Mapbox that inspired my talk Writing for everyone.
…I thought I’d share some of my personal writing tips. Just a few things I picked up from teaching (synchronous), my instructional design days (asynchronous), and for-fun blog writing.
Hey, dummy.
To reassure the reader, you might want to say, “It’s easy!”. Unfortunately, that can backfire. If your reader doesn’t agree, then s/he will probably bail. I like to assume that everything is hard.
I recommend checking out Chris Coyier’s Words To Avoid in Educational Writing and Brad Frost’s Just.
It all depends on context, but here’s a quick hit list of words you might want to avoid:
- just
- easy or simple
- of course
Jargon meet Acronym. Acronym meet Jargon.
I like to introduce jargon or acronyms like I would introduce two people. Start with full names and explain what they do. Then after that they’ll start using first names, have inside jokes, and start hanging out without you on Instagram.
Who did what in where?
After the file is saved…
Wait. Do I save the file? Does the file save automatically?
After you save the file…
Got it, I save the file.
If the user needs to do something, tell them!
Easy on the scrolls
I’m an offender of scrolling on a page just to get to the good parts. I like to make it easy for others to do the same.
Here are a few tips:
- Use headings to chunk up content into sections.
- Write each section so that it’s strong enough to stand independently.
Reorganize
I find that fat paragraphs can be exhausting. If possible, I’ll use a table or list to make it more digestible.
| Instead of this | Try this |
|---|---|
Each completed well drilling application must contain a detailed statement including the following information: the depth of the well, the casing and cementing program, the circulation media (mud, air, foam, etc.), the expected depth and thickness of fresh water zones, and well site layout and design. |
With your application for a drilling permit, provide the following information:
|
Keep it plain
I keep a dictionary with me almost every time I read a book. Because big words. When writing a tutorial, I try to avoid words that might make a reader reach for the dictionary. I don’t want to overload the reader or make him/her glaze over. Instead, I strive to write in plain language.