JustJimAZ

How to Write a How-To Part 2

Rate this Entry
Picking up from last time, you have your vision, your documentation, and your audience in mind. Now let's talk about...

Step 4: Your Voice

This is how you write your piece. You know your audience, so this should be easy. We are just like you. This is not a doctoral thesis where you get bonus points for using SAT vocabulary words. No one (almost no one) is reading your tutorial trying to catch a grammatical error. If you can generally be understood when you speak, then write like you talk. I find talking directly to the audience reads better than trying to write a technical manual.


You should write like you talk, but be clear, and avoid too much slang. If you are a technical person like an engineer, avoid insider jargon. Your English need not be perfect, but it should be readable.

Please read your tutorial before you post it. A tutorial full of misspelled or misused words is distracting, not informative. Use your spellcheck and if you aren't certain what a word means, maybe you shouldn't use it. Make sure your subjects agree with your verbs (They are, not They is). Read it out loud, to yourself or to someone else. You might be surprised how much different a sentence seems when you hear it read. If it's unclear, it will confuse your audience.


Step 5: The Stuff


I know others might have started here, but I truly believe that the first 4 steps are critical to getting the rest right. "The Stuff" means all the materials you are going to use. You might not know what these are until you are completely finished. I rarely do.

Compiling a list of what people will need up front helps your audience determine if this project is for them. You might list the tools required as well as the materials - especially of some special tool or skill is required. If I look at a project list and see welding is required, I know I'm probably not building this - unless JB Weld will suffice! It will also help people estimate the cost. Some tutorials list costs, and I think that's great. The info gets old quickly though. Personally, I usually stay away from listing prices. They vary wildly from region to region anyway.


Source your materials if necessary. Remember that at least part of the purpose behind a tutorial is to help people avoid mistakes. You want them have a chance to start the project with everything they need right up front. If something is hard to find, make sure you let them know where to find it - provide a link if you can. Great Stuff can be picked up just about anywhere, but if your project requires an MP3 player that can be triggered, they are not going to get that at Wal-Mart.

On a related note, I prefer to cite name brands whenever it might be relevant. I use Great Stuff. I buy Krylon Fusion for plastic. I love JB Weld. I do not know what my audience will think if I tell them to use spray foam, spray paint, and epoxy. If it truly does not matter, then I guess generic terms are fine. Personally, if I want to duplicate your methods, I want to know what you actually used. Try going into a hardware store and just asking for latex adhesive. They don't know what their adhesive is made of, only what it is used for. How is that going to help you? Are you laying carpet? I doubt it.

Oh - this is one place where technical terms can be appreciated, too. No one wants to go to the hardware store to ask for "some of those S shaped metal things" or "the sticky blue stuff" or whatever. You want to make it as easy as possible for them to follow in your footsteps, right?

Step 6: The Steps

This is the heart of the thing, right? The actual steps. Where to begin? Well, at the beginning is good. You have your stuff, you have your goal. What do we do first?

I think it's important to note that what they should do first is not necessarily what you did first. Maybe your how-to is on something you've done a million times, but most often it's on something you've done only once. Odds are, you could do it better if you did it again. Give them the benefit of experience.

Assume your audience is smart but inexperienced. I don't mind telling you my children are very bright. It is almost embarrassing how high they score on those standardized tests. What they don't have is experience. They don't know how to do these things, or what tools are required. I must show them. Your audience may know most of the techniques you used, but what if they do not? You'll lose them or leave them with questions.

Try to anticipate questions and answer them before they come up. By following the first steps, you've already answered many questions. What others might they have? Do you prefer Bucky for this project or Blucky? Why? Would the other work? Why do we bend the wire before we put it into the bird? Does the color of the light matter?

The better you understand why you made your project the way you did, the better you can anticipate questions.


I believe that like pictures,when it comes to steps, more is more. You ever see those "how to draw" tutorials? "Start with a circle. Add another circle. Now fill in the details." What? If I could fill in the details I would not be reading the book! Step by step to me means baby steps. "Choose your lid. Sand the lid. Clean the lid. Spray paint a base coat. Let it dry on a cookie rack." That's step by step.

Remember - smart, but inexperienced. If you need them to do arc welding, you better show them how. If they need to do some sandcasting, explain the process. One step at a time until they get where they are going. Tell them when, tell them how, tell them why, tell them their options. They will thank you for it.

Until next time, happy haunting!
Categories
Uncategorized

Comments