Tip 25 - just follow this one simple tip

Jul 18, 2024

One common docs tip is to avoid words like “easy” because it’s not up to you to say what is or isn’t easy for someone else.

Many people have already incorporated this tip into their docs writing practice and are quick to stop themselves when they are tempted to write “easy!” or “simply!” It’s wonderful that this “easily” makes everyone’s lists of top 10 docs tips!

But, the trick isn’t “simply” to remove a few specific words from your vocabulary. (As if that’s a simple thing to do!) Often, we make things sound like they are easy because we are excited to tell you how easy they are. Docs that use the word “easy” typically don’t take a dismissive, superior tone, talking down to a reader like they should totally get this already and why don’t you understand?!

We use words like “easy” because we are enthusiastic! And, our excitement itself can betray our best intentions, causing us to imply that things are easy without saying the word directly.

One PR suggestion I often make is to consciously tone down excitement, and stick to a dry, factual tone.

✅ To use Starlight’s <Steps/> component with an existing Markdown ordered list, wrap…
😐 All you have to do to convert a numbered list into Steps is just…

Injecting your positive engergy into your documentation carries the risk of not meeting your reader where they are. Have you ever had a service provider be a little too cheery for your current mood? When you are excited, things seem easy to you. In that situation, you have to work hard not to make everything sound like it should be “easy.”

It’s also entirely possible that your reader… just isn’t that into your project. They may be forced to use it. It may be their job to use it. They may even hate using your project. You can’t assume that every reader is an enthusiastic, or even willing, user of your project.

And that’s OK! It’s not your job to motivate, entertain, or compensate for the situation that led them to needing your documentation. Don’t try to “cheer them up.” Just give them what they need with the least friction possible.

There’s a joke about writing (code or docs!) as if your reader is angry, confused, frustrated, and knows where you live. I like to make a similar joke about writing my docs as if I am tired, grumpy, and yelling to someone upstairs while trying to keep three cats off of my keyboard. That’s probably a more accurate picture of my reader anyway!

See the whole list of tips!

Toggle Comments