1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
|
The Wired How To Wiki is, obviously, a wiki and that means you, yes even you, can submit how tos to educate your fellow reader. But some of you may be scratching your head, I've never written a hwo to before you say, how does one do that effectively?
Well fear not my fellow hackers, tinkers and DIYers because we're about to get meta on you. Yes, a how to on how to write how tos.
However, before we get into that be sure you look over The How To Wiki's official [http://howto.wired.com/wiki/Editorial_Guidelines editorial guidelines], while they don't delve into the art of writing a how to, they are chock full of advice on the technical aspects of how to submissions. You'll also want to get up to speed on the [http://www.mediawiki.org/wiki/Help:Formatting Media Wiki formatting syntax] (don't worry it's pretty simple).
==What Should Your Write About?==
There's something of a misconception that in order to write a how to you need to be a guru or standout expert in the field. In fact you don't need to be anything of the sort, you just need to have the answer to a common problem we're all likely to face.
For instance, even if you don't know much about Botany, but you have grown a [http://howto.wired.com/wiki/Build_a_Square_Foot_Garden square foot garden], or maybe you know some [http://howto.wired.com/wiki/Do_Bar_Tricks bar tricks] that'll put the rest of us to shame.
In other words, write what you know and don't worry about what you don't know. Your fellow readers will be sure to correct you should you stray beyond the limits of your understanding.
==The Nuts and Bolts of Good How Tos==
=== Assume Nothing ===
The number one rule of a good how to is never assume. Never assume your reader will understand any gaps between step 1 and step 2. Writing a good how to means taking the very complicated and breaking it into clear, easy-to-follow steps.
Don't be afraid of lists, in fact they can be your best friend. Provide clear steps from beginning to end and, if it will help, add screenshots, photos or sample files to show what you're doing.
The goal isn't just to complete your sample project, but to provide enough background information that the reader can extrapolate your example to fit their own situations and needs. And in order to do that you're going to need to be thorough.
That said, you needn't explain everything in minute detail. For instance, writing something like: "now go to your applications folder, select the Dreamweaver folder, navigate to Dreamweaver and double click the icon to open Dreamweaver" is unnecessarily long and will only serve to confuse the reader. Just write: fire up Dreamweaver! or something similar.
It takes a bit of practice to figure out when to include excruciating detail and when a short and sweet sentence will do the trick, but eventually you'll get the hang of it.
=== Taking the Long Way Home ===
Another area that deserves mention is the long way versus the shortcut. There is almost always more than one way to solve a problem. Although there are exceptions, we find that starting with the long way lays the groundwork for the shortcut.
Once you've walked the reader through the longer way, show them the shortcut and explain why the shortcut works and how it saves time and effort.
For example, in our guide to electricity around the world, we cover all the details you need to charge your devices, but then afterward also point out that you can use your laptop as hub and charge other devices through USB cables.
It's an obvious shortcut, but without the background readers might not see why using USB is such an advantage.
=== There be Dragons ===
When you're testing code or coming up with your initial idea be sure to record your notes as you progress and note any pitfalls you encounter. This is the sort of information you readers need to know.
For example in the how to on recycling e-waste, there's a notes about the potential flaws donating old computer equipement. While older gear is often donated with good intentions, it still ends up in developing world landfills because it's broken, unusable, too obsolete or unneeded. It's details like that that you readers will appreciate.
Generally we find it's best to work these sort of notes end after your initial walkthrough of you code. For instance a structure like this works well:
# step 1
# explanation and reasoning
# note any potential gotchas
# step 2
# etc
==Writing Style==
This is the hardest part. We can't make you into a good writer in one tutorial, but here are a few tips that'll help improve your prose and make your how tos easier to read (see what I mean about lists?):
# Use short declarative sentences and don't try to impress the world with your vocabulary
# Learn the basic rules of punctuation and grammar.
# Avoid jargon -- Techincal subjects often require you to use precise terms, but avoid things like "buffer" when more people will understand the term "file." Sometimes it's better to sacrifice a bit of technical correctness in favor of simplicity.
# Be consistent with the technical terms you use -- Don't refer to "Folders" in some cases and "Directories" in others. Pick one and stick with it throughout.
# Proofread -- have someone else read through your tutorial before you give it to the general public.
Never underestimate the value of humor. Try to work in a joke or pun if you can, even if its so bad the reader cringes. Don't worry, cringing is a form of engagement and that's a good sign.
== Additional Tips ==
# Before you start typing, make an outline. It'll help you to organize your thoughts and see the connections between each step in your tutorial.
# Along the same lines, create a table of contents
# Write your how to out in longhand. This forces you to slow down and think about each step (it's not for everyone, but many of our authors find it useful)
# Sit down and follow your own how to, step by step, and make any adjustments if it isn't working for you.
# Have a friend or colleague who's not familiar with the subject read your how to and see if they can understand it.
== Final Thoughts ==
The How To Wiki is a wiki and that means anyone can edit your tutorials, and chances are they will. Some this can be a bit hard on ego, but try to keep in mind that what you find self-evident may not be entirely clear to everyone. Even those of us who've been contributing to Wired for years can always learn something new from our fellow reader.
Once your tutorial is live, be sure to subscribe to recent changes RSS feed so you can keep track of what others add to your work. Not only does that help you maintain some control, but you might learn something new from your fellow readers.
|
