Five tips for improving your technical writing and documentation.

Get more users and fewer support requests by leveling up your writing and technical documentation.

Write like a human, not a machine.

Don’t be afraid to be funny, creative, and a bit silly. I love and encourage personality to shine through your writing. Reading is so much more enjoyable when you sound like a human having a conversation with your reader, rather than dictating instructions.

Yes — not only did I use a made-up word, I also referenced pee in my dedication. #professional
Little “Woohoo!”s can make writing feel more fun, friendly, and accessible.

Remember that your readers aren’t exactly like you.

This happens in a lot of “advanced” level writing. The writer feels like there should be a certain level of knowledge needed before using their project, so they skip over explanations and instructions. After all, advanced-level readers should know all that, right?

Helper #1: Create a persona and write for them.

Try to think of ways your readers could come to your project without having your exact skillset, and give those ideas (personas) a name. You could think of, “Dave, a sysops with experience in C but not in Node,” and review your text, then switch over to “Carol, a developer lead,” and try reading what you wrote from that different perspective.

Helper #2: Take a break from your writing and come back to it later.

Sometimes you just need to step away for a bit (a couple hours or even overnight) to see your writing from a different perspective. Try changing locations, or changing projects for a bit. Going back and forth between contexts can sometimes shake some new ideas loose.

Helper #3: Run your writing by a friend, colleague, or helpful stranger.

Getting a second pair of eyes on your writing, even just a review, can help you find issues. Friends can especially help find places where you’re skipping instructions or where your writing feels robotic.

Helper #4: Use gender-neutral terms.

I see this so often in writing about startups and entrepreneurship:

“The founder should do this, and then he should do this.”

As I’m struggling to be validated as a female entrepreneur, those references are immediate reminders that I am usually assumed not to be a founder. That’s the kind of feeling women in the tech industry gets when your writing includes only male pronouns.

Helper #5: Remember that terms are obvious to you might not be obvious to others.

To illustrate this, let’s take a look at the world of cooking. If you’re new to cooking and open a random recipe, you’ll likely encounter terms you haven’t seen before:

Cut down the amount of content you have and use appropriate formatting.

Huge paragraphs and essay-like blocks of text are intimidating. People don’t read on the web — they skim — and a huge block of text won’t be read.

  • Cut down your content to two to three sentences per paragraph. No use blocks of text.
  • If you can’t shorten a paragraph, try breaking it up into bullets to make it easier to skim.
  • Use italics and bolding to highlight the relevant parts of your sentences. These bits will catch the eye and will invite the skimmer to read the entire block of content.

Simplify your language

Don’t be fancy and break out the thesaurus when you’re writing. Simple, clear writing not only is easier to read for English-fluent folks, but it’s also easier to translate into other languages. Don’t forget someone could be reading your documentation and writing using Google Chrome’s translate feature. Simpler language will be easier to translate.

Add multimedia like screenshots, videos, and gifs to illustrate your writing.

Add helpful screenshots and multimedia when you’re writing instructions and guides.

Written instructions, then a screenshot with the button you’d be looking for.
This was originally given as a presentation at Write The Docs North America 2016



Author of Hello Web Books. Traveling the world and climbing mountains.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Tracy Osborn

Author of Hello Web Books. Traveling the world and climbing mountains.