Technical Writing 201

Why does Tech Writing matter?

Without tech writing, you'd be stuck reading code.

Events and talks inspire a few devs, at one time.

Good writing? Inspires tons of devs, over a long period of time.

Types of Technical Writing

  • Documentation: The least interesting, but most important. Explains how to use a tool.

  • Concept Explanation: Details a concept, like an architecture style, and encourages discussion of that topic.

Types of Technical Writing

  • Tutorial: Shows readers how to use a tool, write a piece of software, with a narrative.

  • Project exposition: Goes over the bird's-eye view of a project, common for open-source releases.

How to improve your Tech Writing

Tell a story

Include a Narrative

  • What's the problem you're solving?
  • What problems did you face?
  • What was your 'light bulb' moment?

Giving your post a narrative makes it easier to follow, and keeps your writing organized.

Use present tense

In your title, and probably in your post.

This helps readers relate, and engage, with your writing.

It also helps you think like your readers.

Open-ended questions

Use them, but a little goes a long way.

These get your reader really thinking about the subject at hand.

Challenge your readers

At the end of your writing, challenge your readers to take your example a step further, or include a call to action to check out your repository.

Cater to a wider audience

At an event, you can assume a specific skill level or background.

You can't do that as much with technical writing- you're reaching a much larger audience (hopefully!)

Set up the audience in your intro

Address what skill level you need to understand the tasks/ideas in your writing.

Make a clear statement as to what exactly you're covering- especially if your title is ambiguous.

Show them your environment

If you're showing code, list what version of the language, dependencies, what software you're using.

The reader should be able to easily figure out if something's different should the come across a problem.

Links, Links, Links

Dependencies, needed software, other tutorials - link to the information instead of trying to shove it into your own writing.

Put the links where they are relevant, or most useful; long download needed? Put that near the beginning.

Manage your example code

General Rule of Thumb: If someone copy/pastes your code out of your post, it should run.

Don't show huge blocks of code

Show a small bit of code, then explain what it does. This allows the user to grasp what's going on.

Just because you can read the code when it's all together, doesn't mean your reader can.

Other general principles

Build debugging into your sample code- especially where output is expected.

Have a link to the full source (Stash, Github) near the end of the post, so readers can see the full piece of code when they choose to.

Use images / diagrams effectively

Images/diagrams as a tool

Don't replace text with images and diagrams, augment with them.

Make sure your images are relevant to the text around them. 

Use images to illustrate your narrative

If you're writing about building a piece of code, show terminal output/screenshots as you go.

This is especially true when working with signup forms, APIs, and hardware- give your users a visual trail to follow.

Use promotion / analytics

Build a media list

Did you use a particular library/framework? @ them on twitter!

Local user groups on the subject would like to see your writing.

Use other people's interest in the topic

Use analytics to determine what works

When you see where your traffic comes from, you know who to contact when you write again on that topic.

You'll also see which posts hold over time, where your users are going, etc.

Show personality / voice

Using your voice

Readers always react well to writer's voice, even in tech writing.

Don't force it- just be yourself.

If you're going to be funny, be dinner-table funny, not bar-buddy funny.

If you're taking the time to write, you're probably excited about the topic- let that show through, and your readers will get excited too.

Peer Reviews

Always* have your work reviewed

* - I'm not kidding.

It also helps, for tutorials, to have someone who hasn't done what you're writing about to run through your post.

Have your reviewer check/run your example code, too.

But I don't know what to write about.

Yes, you do.

The 'Google' Rule.

More tutorials never hurt, more docs never hurt.

Yes, we can definitely use more posts for the RMN Eng Blog.