Menu

How to Create High Performing Docs

2022-08-22

When it comes to technical content, no one wants to read what you write.

Read that line again.

Readers want solutions and to get back to work. The following tips help can help you craft the best possible experience for your readers.

🎯 Define the “what’s in it for me?”

Figure out what your reader’s intent is up front. Once defined, orient all the content in your article toward this target.

💡Put off writing until reader intent is crystal clear - then work out from there.

✍🏻 Create elevator pitch introductions

Your introduction should help readers figure out if they want to read on or leave as soon as possible. Favor terse, but dense introductions that summarize your content.

💡Write your introductions last. You’re in the best position to summarize your content at the end.

📰 Write headlines that summarize

Ambiguous article titles are as annoying as they are confusing. Sum up the intent of your article in a single line.

💡 You get bonus points for mentioning key technologies in your title.

📏 Keep it short

Please 😉

🔎 Make it scan-able

Making readers plow through paragraphs of text is taxing. Most often readers scroll through an article trying to find what’s most important to them. Optimize your content to this behavior by making information stick out.

💡 Add sub headings, images, and pull quotes where appropriate. Favor numbered and bulleted lists over strings of sentences.

🔪 Edit ruthlessly

Don’t keep every word you write.

💡 Go through your text multiple times to find the most succinct way to express your ideas.

🖼️ Create clean images

A picture is worth a thousand words, but confusing images can destroy your message.

💡 Make every element in a graphic serve the image’s purpose. Remove extra UI elements, increase font sizes, and zoom in if you must. Discard unnecessary dead space and anonymize personal identifying information.

1️⃣ Write on one topic

Make each article about a single subject.

💡 Expressing one topic at a time allows you to reduce cognitive load and keep your message focused.

🥁 Create cadence

Pair short sentences with long ones.

💡 Just as in verbal communication, flow affects how people receive your message.

📖 Start with the story

While writing docs is nothing like crafting a novel, there is still a story to tell. The concepts, procedure, or code is the foundation for your content.

💡 Build your sample code first, then tell your story through your article.

🦸🏻 Make the reader the hero of the story

Avoid third-person pronouns.

💡 The reader is doing the action, so make your directives oriented toward the only person who matters.

Summary

In the end, technical writing is an exercise in empathy. Visualize your reader to picture how you can make their life easier in the shortest time possible.

Remember to:

  • 🎯 Define the “what’s in it for me?”
  • ✍🏻 Create elevator pitch introductions
  • 📰 Write headlines that summarize
  • 📏 Keep it short
  • 🔎 Make it scan-able
  • 🔪 Edit ruthlessly
  • 🖼️ Create clean images
  • 1️⃣ Write on one topic
  • 🥁 Create cadence
  • 📖 Start with the story
  • 🦸🏻Make the reader the hero of the story