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
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
|
Webmonkey is a wiki and that means you, yes even you, can submit tutorials to educate your fellow monkeys. But some of you may be scratching your head, I've never written a tutorial before you say, how does one do that effectively?
Well fear not my fellow web programmers, designers, tinkers and hackers because we're about to get meta on you. Yes, a tutorial on how to write tutorials.
However, before we get into that be sure you look over Webmonkey's official [http://www.webmonkey.com/services/Editorial_guidelines editorial guidelines], while they don't delve into the art of writing a tutorial, they are chock full of advice on the technical aspects of Webmonkey submissions. You'll also want to get up to speed on the Media Wiki formatting syntax (don't worry it's pretty simple). There are some handy links on our [http://www.webmonkey.com/services/FAQ FAQ page].
==What Should Your Write About?==
There's something of a misconception that in order to write a tutorial 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 every tiny detail of PHP, you might know enough to teach us all how to build a WordPress extension. Or, while you might not know how to compile Apache from source, you know how to set up virtual hosts, so teach us how to do that.
In other words, write what you know and don't worry about what you don't know. Your fellow webmonkeys will be sure to correct you should you stray beyond the limits of your understanding.
If you've ever spent three hours filtering through Google search results looking in vain for an answer to some programming problem, and finally, after a bunch of aborted attempts based on other's suggestions, you have one of those ah ha! moments, chances are you just stumbled on a good tutorial topic.
Of course that isn't always true, but it's a good place to start.
Another key thing when starting a tutorial is know what you don't know. Writing a good tutorial means being humble enough to admit when you don't know something.
==The Nuts and Bananas of Good Tutorials==
=== Ass U Me Nothing ===
The number one rule of a good tutorial is never assume. Never assume your reader will understand any gaps between step 1 and step 2. Although we provide a way to rank the skill level of tutorials, don't just select advanced and assume that reader will be able to fill in any gaps in your tutorial.
Writing a tutorial 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 or sample files to show what you're doing.
When it comes to code snippets don't just throw them out there. Throw them out there and then walk us through it line by line, explaining why we're doing what we're doing as much as how we're doing it.
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. Especially in programming, 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 Python much of what you do with for loops can be done with list comprehensions. However for loops exist in nearly every language and there's a good chance the reader is already familiar with the basics of for loops. So our intro to Python tutorial presents for loops (the long way) and then moves to list comprehensions which are a shortcut unique to Python.
=== Code ===
When it comes to code the rule is test, test, test. Test in different environments, on Windows, on Mac, on *nix on Symbian and so on. Testing serves two purposes, first to make sure you code works, but also, when it doesn't to help you learn right along with the reader.
If your code works on Mac and *nix servers but not on Windows, find out why and explain that to the reader.
Also bear in mind, particularly with web programming, that not every shared host server is going to have the same set up. For instance, if you're writing about editing Apache config files, keep in mind that not everyone has access to root Apache files, so it would be wise to include .htaccess alternatives.
Same goes for programming languages, if you're talking about features in the latest version provide possible alternatives for those still stuck with older versions.
=== 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 forgetting a semi-colon in PHP is a common error, add a quick note somewhere reminding the reader to check their line endings. In Python the old spaces/tabs mixture is a common problem so mention it. You needn't get into why you need semicolons or only tab indentions, just note that the potential pitfall so the reader is aware.
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:
# code sample
# line by line explanation
# note any potential gotchas
# next code sample
# 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 tutorials 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 -- Programming often requires 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 a flash movie as a .swf, then a "flash movie," then a "flash file," then a "movie file." 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.
Another aspect of a good tutorial is the voice. Webmonkey has many authors, but a fairly consistent voice which helps create familiarity and comfort for regular readers. Make sure to re-read your favorite tutorials and try to get a sense of ''how'' the author says things as much as what they say.
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 tutorial 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 tutorial, 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 tutorial and see if they can understand it.
== Final Thoughts ==
Webmonkey 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 Webmonkey 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 monkeys.
|
