Thursday, October 6, 2011

The How-To on How-To's Part II (Writing Style)

Here we are at part 2 of my how-to on how-tos.  By breaking this tutorial-writing tutorial up into sections, you have a little more time to focus on each aspect of writing a good tutorial before I throw the next bunch of information at you.

Last time I covered the importance of using photos in your posts (feel free to review that before we go on, I'll wait), so that brings us to:
Intro: The purpose of publishing tutorials is, in short, to help people.  Admittedly, tutorials are also a great marketing tool with which to showcase your knowledge, writing style and/or craft, but if it doesn't teach people how to do something, then it has failed at being a tutorial.  If you're writing for yourself, or if your audience is unable to understand you easily, your time would probably be better spent elsewhere.  Harsh.  I know, but there you have it.

Use a structured format. I dig literature. I have a love for Joyce's stream of consciousness literary style and the long, meandering story-telling of American writers from the Deep South.  However, rambling in a tutorial makes me click away quicker than green grass through a goose. True story.  Have you ever wondered why I use bullet points so often? Outline formatting is a habit I picked up from my years of writing licensing contracts and doing regulatory analysis. It works so well for instructional writing that I use it often in my posts.

An outline format:
  • is easy to read
  • stands out on the page - it says "here are the instructions!" and 
  • makes referring back easy; your reader won't have to scan through long paragraphs to find information
  • serves as a checklist when printed out
Write simply.  Don't plan on getting mileage out of your fancy vocabulary in a tutorial. Instructions are difficult enough to follow without making readers stop to look up words like "contiguous" (just say "next to each other").  If you choose the simplest, most concise words to describe what you're doing, your tutorials will reach a wider audience base.  People will also make fewer mistakes (read that as "get less frustrated") which means your popularity as a tutorial writer will grow.

Be conversational.  You aren't writing a scientific research paper for publication in the Journal of the American Medical Association, so you should feel free to engage your readers in conversation.  Heck, use  colloquialisms (well-known expressions or slang) or crack a joke every now and then; nobody is going to rap you on the knuckles with a ruler for goofing off in class.

Here is a trick I used in college when I was a writing tutor: try reading your instructions aloud.  Do they make sense?  If you find yourself tripping over sentences or words, revise those parts. Whenever I read my tutorials to my husband, I edit as I go.

Use proper grammar and punctuation.  I cannot stress this enough.
Not sure about proper punctuation?
Periods and commas are
nothing to be ashamed of.
  1. Colloquialisms and jokes are great, but never use LOLspeak, SMS or texting abbreviations, leetspeak or any other form of un-grammar in a tutorial (exception: if you are writing a tutorial on technology-based "grammar").  If you use any "txtese" in your tutorial, 
    • Best case scenario: you exclude anyone who doesn't understand what you are saying.  Why bother writing a tutorial if most people can't or won't read it?
    • Worst case: you come across as irritating, uneducated and/or too lazy to write a sentence.  Yipes.
    • All the squiggly red lines under your abbreviations are going to distract you from the other spelling errors.
  2. Spelling is pretty easy to check with a spell-checker, assuming you haven't used the wrong version of a word like "then" instead of "than."  Common grammatical errors, I'm sorry to say, will also turn off many readers.  If you are unsure about when to use "its" and "it's" (that's a confusing one, too), just do a quick search on Google.
  3. My current pet peeve is misuse of the ellipsis (aka "dot dot dot").  These should be used only when something is left out of a quotation or is intentionally left unsaid.  If you want to pause, try our old friend the comma or live wildly and start a new sentence.
    Ellipsis have three (3) periods "..." (a fourth is optional, but only at the end of a sentence).  Adding an extra 12 in a Facebook post might be cute, but in a tutorial, not so much.
  4. Use a reference book.  OK, this is for the hard-core of us out there, but it is an option. Most people have thrown Strunk & White to the wind in preference of On Writing Well, but my favorite is The Deluxe Transitive Vampire.  It's funny, helpful and it makes a great conversation piece when people see it on your bookshelf.  People ask me about that book more than they ask about my gigantic O.E.D. (acquired in ye olde pre-internet days).
  5. And the simplest tip: have someone read your work or proof it the next day with fresh eyes.
Sure, you could go with Elements of Style, but
why would you want to? This is so much cooler!
I know, you're probably shouting, "Krissi! This post is chock full of rules to remember!"  Well, don't get too panicky about them. Just work on communicating what you want to say in the simplest manner possible.  Pretend you're having a conversation with someone and avoid the temptation to fancy up your language to "sound like writing" or to use punctuation you aren't sure about.  After that, just proof it with fresh eyes (yours or someone else's) and go for it.

Next time:  Links!