Well, this risks getting terribly meta, doesn't it - a tute on writing tutes. But I've been teaching myself Dojo lately (it's a javascript toolkit. Just nod and smile, there won't be questions), trying to combine a book that's about six versions behind with web tutorials that are one version behind, and I've come to a rather disappointing conclusion: very few people on the internet know how to write a good tutorial. 

I suppose that's reassurance that my day job has a real purpose, but it's rather disappointing that the basic fundamentals of education and communicating information are lacking in so many otherwise-clearly-very-intelligent people. The way our current online-society is going, it should really be something taught in fundamental education: communicating your ideas clearly and concisely, how to think from the point of view of someone who knows nothing about what you're teaching them.

So here's my Tutorial Writing 101: Entertaining Subtitle. (I'd like to claim that as being all meta, but really I couldn't think of a good subtitle that didn't involve swearwords. It's been that kind of morning.) In the interest of following my own advice (below), to get the most out of this tutorial you need to have:

• a high-school level grasp of lanauge, (your language of choice, and English in order to read this. Duh.)
• an ability to empathise with people who know less than you (not sympathise. Emphathise. As in, put yourself in their shoes.)
• basic language and concept analysis skills
• something you want to write a tutorial about. 

 Focus your tutorial

A tutorial should be about one core concept. Even introductions and overviews need to have one idea they're working from. Without a single core concept, there's no cohesion - the ideas don't "stick together" and build an understanding. Instead, they skitter around like excitable kittens, colliding and shredding the furniture. When we learn, we connect concepts together and link them in with something we already know - that's why we use analogies, why people ask you what you alreayd understand before teaching you something new, and why each year in school they teach you a little more maths, science, french and philosphy. If the concepts you're teaching someone don't connect with each other and what they already know, they won't be learned.

It helps to boil your tutorial down to one sentence - one core concept that you want to communicate. That sentence should not be "how X works", or "what you can do with Y" because that doesn't help you focus (unless X is a very simple concept, or you can only do three things with Y). You can either choose a question that you want to answer ("How do I refactor my quantumn coordinates?") or a statement that you want the reader to be able to make at the end ("So I should refactor my quantumn coordinates to prevent a buffer overflow in the outer matrix"). If you can't identify the sentece for your tutorial, most likely you're trying to teach something too board. Focus, and split it across a few tutorials if necessary.

Write for the right audience

The problem with most tutorials you'll find online is that they're unintentionally written for someone who is just behind the tutorial-writer in their understanding of the subject. Essentially, the writer is fixated on explaining X, but in focussing on that ("what do they need to know about X? Okay...")  they forget that they're assuming their readers already understand Y, Z, A, B and C. As people, we default to assuming everyone is like us - that they have our moral values, our level of ambition, our experience, and therefore we explain it to them as we would to ourselves. 

Unless the reader is following the same learning path as the writer (unlikely, unless they're both using university study), something is almost certainly going to be missing, because the reader has taken a different learning path (they may know G, H, J, Z and Q, but not A, B, C or Y) or not-quite-right because the writer and reader's understanding of Z differs slightly.

Outside of a structured learning environment (school or paid-tutorial course where you know people can't get to tutorial 3 without going through 1 and 2) you can't make assumptions about what your reader does and doesn't know. Even if they're reasonably well-versed in some areas, they may have completely missed other seemingly fundamental aspects of the subject. In a lot of situations certain knowledge is a prerequisite, so this poses a problem: how do we communicate advanced information when we can't assume our reader has the requisite knowledge?

Identify the prerequisite knowledge

The first step is to work out what you're assuming they already know. This is where some of your analysis skills come in. You may want to brainstorm, mind map or just list them, but it's important to physically list - not just mentally but write it down - what information the tutorial is using (even if you haven't written it yet. Especially if you haven't written it yet.)

If you're having trouble with this, then just write down everything you know about the subject. Point form and abbreviations will do (essays are not helpful, here). If it's a large subject (for example, an entire programming language) then focus on what you know that relates to the tutorial topic, however tangentially. (If this seems like a lot of work, then keep in mind that you can re-use this list for future tutorials in this subject. Don't skimp.) Once you have your giant list, narrow it down to the concepts the tutorial is actually using. Depending on how you think, you may find it easier to do this after you've written a draft of your tutorial. If that's the case - go ahead, write the draft.

Keep both these lists. The large one, as mentioned, can be used as a starting point for later tutes, and the "what this tute needs" one we'll use as a checklist later.

Remove any unnecessary prerequisites

Again, this step may be easier with a tutorial draft in hand. You need to go through and find any areas where you can remove prerequisite knowledge - the more things someone needs to know to use your tutorial, the less accessible it is. You can remove prerequisites by either providing an explanation for the concept or excising (removing) whatever is using it in the first place.

The explanation-solution should only be used for things that can be explained clearly in one sentence. See above where I introduced a word not necessarily common to most people's vocabulary (excising) and immediately provided a simple explanation. This only works if the explanation is short and simple enough that the reader doesn't lose the flow of the original sentence. Contrast with: "You can remove prerequisites by either providing an explanation for the concept or excising (where you take something away from something else because it shouldn't really be there or you thought of something else to put there instead that would work better) whatever is using it in the first place."

Note how that large, rambling sentence really disrupts the flow - it's hard to remember what I was talking about outside the brackets. And remember, you already knew what that sentence was supposed to mean, because you'd read the simple version above - imagine if you were trying to understand my point, not entirely familiar with what I was talking about anyway, and then came across that great huge rambler mid-sentence like that. All the ideas that you'd been carefully chaining together to follow the tutorial fall apart because you have to stop and pull that sentence apart.

If you can't explain it simply, ask yourself if it really needs to be there - can you find a way to explain this section without using that knowledge? Don't think of it as 'dumbing down' - you're not going to write it in baby-talk. Just don't use anything that you don't have to. This isn't university: you're not trying to impress anyone with all the things you know, or show your lecturer that you really did do all the readings. This is about making one particular topic accessible to as many people as possible. So if it isn't absolutely necessary to the understanding of your tutorial topic, get rid of it.

Side note: if it's not essential, but rather an extension of the topic (for example, talking about X, and X behaves very differently when you introduce Y) then you can either:

• put it at the end of the tutorial, as a cool little point to finish on after they've understood everything else - but only if it is small enough to be adequately explained in ONE paragraph
• create a new tutorial for X+Y. 

Nobody said tutorials had to be long.

Advertise your prerequisites

So we have identified all the prerequisite knowledge, and we have removed all of them that we could. But we still have some left. That's not a failure, it happens, especially when you're talking about complex topics. There are two ways to treat these:

Prerequisites that can be explained in one paragraph or less should be covered in a "what you need to know" section at the start of the tutorial. Just lay them out, one after the other, and explain them (though if the prerequisites themselves have prerequisite knowledge, you should either adhere to the guidelines below about structuring information, or use the second option).

Prerequisites that can't be adequately explained in one paragraph should be listed, preferably with a link to a page that explains them (wikipedia is typically good, as it provides an accessable overview of many concepts and the pages don't typically move. If you have other tutorials that cover these concepts or know of good tutorials that do, feel free to link those instead or as well.) Don't provide more than two links for a topic or you'll overwhelm people.

It should go without saying that you should read the material to which you're linking to make sure it covers the topic sufficiently for your purposes.

So your tutorial now tells people upfront what they need to know to understand it. This is very important for the process of learning (I'll explain that in a moment). You've just made your tute twice as accessible. 

Layer your lessons

There are a few really crucial aspects that make the difference between a tutorial that looks informative and a tutorial that's actually accessible and helpful. Clarity of language is one of them (and that's a whole semester of grammar studies, really) but even if your command of language isn't top notch, you can still make your point understandable by adhering to simple sentence structures and paying close attention to the structure of your tute.

When people learn new things, they link ideas together in their head. Concept A goes with concept B like this, and concept C fits in like this, etc. When you're just learning something, the links between concepts can be very tenuous, and if you're trying to fit things in that don't link in (yet) the whole structure falls apart very easily.

Structure the concepts

We already looked at identifying prerequisites for the concept; now we need to take a similar approach within the tutorial. There are two ways to do this, depending on how you think:

The first is to look at the concept as a whole, and ask yourself "what does the reader need to understand first before they can understand everything else"? Note that this is not the most important thing, or even the key point of the tute. This will likely be something very uninteresting. But in order to follow the rest of the tute clearly, they need to understand this information. Then ask yourself "what is the next thing they need to understand that directly connects with this thing?" Then find the third thing that either connects with the first or the second thing. Continue on until all the concepts - your entire tute - have been explained.

If you have a concept that doesn't connect at all, you should firstly reconsider if it really needs to be there. If it does, then wait until you have a good number of connections between the other core concepts before introducing it, so the reader feels they have a grounding in the tute.

The second method is a lot more haphazard; I prefer to use it as a method of testing tutorials rather than planning them. Essentially, you look at your existing draft, and check that:

• each concept that is explained connects to something that has been previously explained (and preferably, not too many concepts ago).
• there is no case where you are using a keyword or concept before you have explained it.

Present information clearly

You've now identified your core concept, what the reader needs to know before they start your tutorial, and what order you're going to present the information in. Now we're down to actually communicating things clearly. 

I'm not going to get into grammar too much here, don't worry (you'll note it wasn't in my prerequisites). There are some simple rules to make sure your message is clear without having to pick up a grammar book.

Break up the tute into headed sections

People like to skim. They'll often skim a tute before reading it to see what it contains, and they like to jump ahead to see if something that's confusing now is explained more later. People also need frequent breaks - the chance to mentally take a breath and solidify that little chain of ideas they were building. The longer that chain gets - the more ideas they're trying to chain together - the more likely it will break and they'll become confused. It's pretty much the short-term memory rule - seven items, give or take two. You really don't want to go past more than five items (ideally, no more than three) before you give people a chance to 'close' that chain over.

Chunking your tute into sections provides them with this - a little sign that says "I've stopped talking about that now, that's all you need to know about that bit.". They may reread over the section again, pause and think about what you've said, try some examples, even go away for a bit and come back, or they may just keep reading on - but when they do read on, they can start with everything you just taught them - all those little ideas - as just one object in their next chain. 

Headings are vital to signpost what you're about to talk about. It indicates to them where this next section should connect to the previous chain. Headings should be clear, simple statements that summarise what you're about to discuss. Avoid 'ing' words, as they're not as clear (I'm not going to explain why, just trust me. Re read my headings above using 'ing' words instead).

Use intros and conclusions

There's a reason we have introductions and conclusions in scientific papers - they aid understanding by providing the 'scene-setting' at the start for the chain-building, and summarising the chain of ideas into one unit at the end. Make use of intros and conclusions to help your reader do that work for them. You'll note that while I don't have an introduction marked out with a heading (it doesn't have to be if that looks naff), there is still a preamble above talking about what problem I'm trying to address.

Sectioning out examples can also help a lot, rather than burying them in the explanations.

Write clearly

I said before you don't need a perfect command of grammar to communicate well if you follow a few simple rules. Here they are:

• Sentences are not a limited resource; you don't need to cram everything into one of them. Don't be afraid of the full-stop. One idea to a sentence. Feel free to use more than one sentence per idea if required.
• Avoid overly long sentences. At the risk of making my grammaphile-friends shun me: if you have more than three commas or more than twenty words, it should probably be split into two sentences. If all your sentences have three commas, you should split some of them into two sentences. If none of your sentences have commas and they're all seven words or less, some of them should probably be combined, but don't combine sentences if their ideas are not related.
  • Eg: "I sat on the bus. A girl sat next to me." These are related and can be combined into "I sat on the bus and a girl sat next to me".
  • But "I sat on the bus" and "Yesterday it rained" are not related. "I sat on the bus and yesterday it rained" implies that you made it rain yesterday by sitting on the bus today, which is probably not what you meant. If in doubt, make them separate sentences.
• Paragraphs should only talk about one concept. A sentence is an idea, a paragraph is a grouping of sentences about the same idea. Do not suddenly start talking about fish in the middle of a paragraph about bananas. Wait until the appropriate fish-moment, when other fish-sentences are nearby.
• One-sentence paragraphs are fine. Eight-sentence paragraphs are fine. But if it's more than three finger-widths on the page, if probably needs to be split because people skim over walls of text. Find somewhere where what you're talking about shifts slightly (ie, when you go from introducing the concept to talking about how it relates to X) and split there. If you can't find that place, just split it where it sounds good to have a bit of a break.
• Don't use jargon (buzzwords, domain terminology, terms that need a definition) if a regular word will do, and put the thesaurus down. You're not here to impress people with your vocabulary. If you wouldn't bet $500 that you know the meaning and spelling of a word, look it up or don't use it.
• Use exclamation marks as if they cost you a kidney. Ie - don't.
• Sentences start with a capital letter, they end with a fullstop. Everything else is sugar; steer clear of any punctuation that you're not confident with.
• Learn the problem homophones (words that sounds the same but mean different things): you're/your/yore, their/they're/there, here/hear, its/it's, etc.
• If you can explain it better with a picture, use a picture.

And finally - get someone who doesn't know the subject to read over it. Which is something that I'm completely failing to do with this one, but I hope if people have comments or clarifications that they'll use the handy comment box below.

Conclusion

Writing tutorials aren't as simple as just jotting down what you think people need to know. It requires a lot of analysis and thinking things through from the point of view of your reader - these are skills that can be difficult at first, but soon become second nature whenever you're constructing a text. If you get into the habit of noticing and managing your knowledge prerequisites, structuring your information in a progression of concepts and presenting it clearly-written in headed sections, you will create tutorials that are much more accessible to readers, and therefore much more useful. Your audience will expand from people who almost knew that stuff anyway to people who know comparatively little about the topic, and your own understanding of the topic will improve through the process.

• Add New
• Search
• RSS

Comments (0)

Write comment

Your Contact Details:

Name:

Email: do not notifynotify

Website:

Comment:

Title:

Message:

Security

Please input the anti-spam code that you can read in the image.

Powered by !JoomlaComment 4.0 beta2