I need a tutorial to make a tutorial

Question

Has anyone seen a good tutorial on writing a good tutorial? It sounds silly but it's a serious question. I'd like to write a tutorial but I'm not sure whether my concerns would be the same as my audience's concerns. Or do I just write it for me and pretend someone else is listening? What's an example of a perfectly executed tutorial? Or is there such a thing? I've read a number of tutorials posted to various social bookmarking sites and thought they were perfectly wonderful only to see them voted down inexplicably. I don't think my delicate ego could handle it so any advice on avoiding that fate would be helpful.

Answer 1

How to write a HowTo: http://forrest.apache.org/docs_0_70/howto/howto-howto.html

Answer 2

Geoff,

Write it for yourself - this is what's really important. I see writing tutorials and articles as the best way to learn some subject - nothing teaches you something like trying to teach it yourself.

Answer 3

Look at how others write tutorials for your audience. Take note of the writing style, structure of the problem, solution and references, and how visual references are used. Also, were you able to complete the tutorials you tried?

Once you write your draft, do your own tutorial a few times. Read and rewrite sentences that could be shorter, have been repeated, or are unclear.

Here is also some general guidelines from eHow: http://www.ehow.com/how_2152866_write-a-tutorial.html

Pick up a copy of the tiny book "Elements of Style" by Strunk and White for some advice on keeping on point and writing well. http://www.amazon.com/Elements-Style-Fourth-William-Strunk/dp/020530902X

Answer 4

Guy Kawasaki has a blog post linking to the The Art of the Tutorial.

That said, I haven’t checked it out.

Answer 5

Writing

• Spellcheck
• Grammar check
• Try to use synonyms instead of repeating yourself
• Write for your users, not the search engines
• Have an introduction and conclusion
• Write no more than you must, no less than is understandable

Presentation

• Vary paragraph length
• Use section headings and blockquotes on the sides to accommodate different types of readers
• Don't let advertising get in the way of content
• Use images when appropriate
• Provide syntax highlighting for your code examples
• Use a readable black font against a white background

Content

• Working code and examples
• Provide a demo where possible
• Allow for feedback and respond to it
• Provide links for more information
• Break the tutorial into easily digestible steps

I should also add, pay special attention to your title as it's the first thing that most people will see. You'll hear the term "linkbait" bandied about far too often, but there is a lot of truth to it. Your title should definitely reflect the content of your tutorial, but if you can make it intriguing, controversial, and informative; all the better. A good way to practice writing titles is to look at newspaper headlines and mimic the same practices.

Answer 6

Firstly. Just do it.

Don't let the fear of crashing and burning spectacularly get in the way. At first you may not be very good at it, but if you're like most humans you'll get better at it. Also, what's great about computers and the internet is that you can cheat a lot. You can fix the errors that people point out and you can improve the piece over time. Or, if it sucks that badly you can just delete it and maybe the pointing and laughing will stop.

Ask for feedback. Hopefully someone will take the time to tell you how you can improve it. Try to understand each comment. Even trolls can sometimes teach us something.

This is writing and like most writing it's more of an art than a science. You can try to follow a prescribed set of do's and don'ts but I suspect the resulting output will be pretty boring. Just use common sense. Your article will probably not fulfill every person's need that reads it, but I'm sure it will help someone.

By not writing you're keeping all that good information all to yourself and that's, like, selfish. You don't want to be selfish do you? Give us all your juicy information.

Answer 7

That sounds just like recursion. See Recursion :D

Answer 8

Get this book:

http://www.amazon.com/Unix-Programming-Environment-Prentice-Hall-Software/dp/013937681X

You should be able to find it second hand for next-to-nothing. The information in it is out-of-date in some places. But as an example of a brilliantly written tutorial, it is probably still unsurpassed. You should shamelessly copy its style.