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
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.
Questions?
Technical Writing 201
By kperch
