I read a lot of tutorials, and most of them suck. 
Sorry, but they do; they almost tell you what you need to know and then you are left hanging; with your code not quite working and you can’t figure out why.
It is time to write down some best practices for writing tutorials; then once the list is complete, you can email a link to the list to the author of the next tutorial you read that sucks.
This is a first attempt; finalizing it will be up to you helping me get it right.
#1 You won’t Be There To Explain
This rule is the foundation of all that will follow. You will not be in the room to explain or clarify, so what you write must be self-evident.
Self-evident means that what you write either does not depend on any previous or other writing, or that other material is referenced.
The exception, of course, is that you can rely on the prerequisite knowledge that is either stated or implied, such as not explaining an if statement in an advanced programming tutorial
The question you have to ask about every sentence, every concept, every piece is this “will the intended audience get this 100% without any confusion, questions or concerns?” For tutorials that don’t suck, the answer must be “yes.”
#2 Know and Explicitly Identify the Audience
Make sure that your tutorial identifies who it is intended for, and make sure you are writing to that audience. Be clear about what is expected… what knowledge are you assuming the reader already has?
#3 Name It Clearly – Make It Easy To Find
There is little point in putting a lot of effort into your tutorial if the folks who need it can’t find it. Help the search engines by giving your tutorial a great name and using key phrases on which folks are likely to search.
#4Provide Complete Source Code
Providing complete source code means showing where your code examples fit in and what you are assuming was already declared. I can’t tell you how many times I read a tutorial and say “yes, but where did that come from?”
#5 Don’t Show Off, Don’t Be Cute
Why is it that programmers writing demo code tend to make the code infinitely more complex than it needs to be?
- Do not use side-effects,
- Use interim variables
- Use self-explanatory identifiers
- Strip away peripheral code including error checking
- Use the least amount of code possible
- Use shorter statements (don’t combine operations)
- Using the least amount of code possible means including everything that clarifies and getting rid of everything extra that confuses.
#6 Walk through your code.
Don’t assume I can read your code like a book. Use line numbers and tell me what you are doing unless it is dead-simple obvious. This goes back to understanding and meeting the needs of the intended audience. It is far better to explain a line of code that I likely get, than to fail to explain a line of code that will leave me confused.
#7 Freshness-Date Your Tutorials and Demos
How many times have you read a tutorial that purports to tell you exactly how to do what you need to do, only to find out that the author was using a now-obsolete version of the SDK? Date-stamp your tutorial and identify which version of the tools and the libraries you are using.
#8 Motivate, Demonstrate, Explicate
- If you tell me to perform ten steps in a row without any explanation of what I’m trying to accomplish you’ve turned me into a mindless robot; the exact opposite of the state in which I can lean anything.
Motivate: Tell me what I’m about to do, or show me what I’m about to build. Don’t keep me in suspense, I want to be working towards a goal I understand, not following your directions mindlessly.
- Demonstrate: Help me walk through the steps or at least show me the steps you took to get from where I was to where I’m now motivated to go
- Explicate: Along the way explain what I’m doing and why I’m doing it that way.
#9 Keep It Short
Blaise Pascal is said to have apologized for writing a long letter, explaining that he did not have the time to write a short one.
Albert Einstein actually said It can scarcely be denied that the supreme goal of all theory is to make the irreducible basic elements as simple and as few as possible without having to surrender the adequate representation of a single datum of experience, but this is usually reduced to Make things as simple as possible, but not simpler.
A short, comprehensive, well written tutorial is gold. A long rambling tutorial may not do much harm as few will take the time to read it. A short, incomplete tutorial is an exercise in frustration.
You can make your tutorial feel shorter by using sub-headings, allowing the user to see what is being covered and cherry pick the interesting parts.
#10 Answer the question “Now What?”
Your demo / tutorial is worthless to me if after reading it I have no idea what to do. Give me a clue: do I need to read your next tutorial? Read something else? Or can I use what you’ve given me, translating from your demo directly to my problem?
#4. Provide Complete Source Code (That compiles with minimal effort).
There have been too many times where i downloaded source code only to find that it would not even load into Visual Studio, let alone compile. Test the code works on a clean machine (with VMWare or VirtualPC this is trivial) so you can be sure what pre-requisites, runtimes, toolkits, SDK’s, and 3rd party assemblies are required. before you turn keen learners into frustrated and disinterested folk.
Nice article.. 🙂
I like my headings to pose the question that the reader should have asked.
Wrong answers, Grasshopper? Perhaps you ask the wrong questions. Edges are the key. Seek them in your understanding, and study them. When you know what it is that you do not know, questions answer themselves and wisdom chuckles in its approach.
@Rainer Hilmer
Rainer, you raise two excellent critical points. I think your best bet at understanding your audience is to invite as much two way communication (via comments, etc.) as possible. One of the most valuable aspects of attending conferences, for me, is the in-hall discussions in which I learn a great deal about who is reading my blog.
As for your second point, what i have in mind is creating tutorials that have a general problem area that is likely to be shared by your readers. Thus, my demos tend to involve either or both of UI and Line of Business issues, but rarely involve games as the translation from a game to a business problem is much more difficult.
I might be talking through my hat because I can’t write a tutorial I’ve tried to for my own use so I have a lot of respect for someone who can that being said I went from an absolute beginner to a point where I’m starting to make some money developing now I still have a long way to go. It would not be possible if it were not for well written tutorials and books by pepole like Jessy Liberty and the Microsoft Crew I agree with your ten most important issues especially the source code and the example code in the tutorial if it all flows smoothly you learn in leaps and bounds but if it bounces around from point to point and back again the tutorial gets confusing and if the code doesnt work any where the whole tutorial falls apart and you find yourself looking for one that dose work. I’ve done well written tutorials that had a typo or a bug in it and because it was well done I was able to find and fix it and learn something along the way. I find real world examples are the best for learning for example Label.Text = TextBox.Text a real world example would be take that text and put it into a data base and then bring it back.
The one point I would make is get someone who is not accomplished to point they can think ahead of the tutorial to review it they just fill in the gaps as they go and tell you great tutorial while someone of lesser ability just sees the gaps hope this helps
Don’t forget to test the tutorial on a co-worker or a friend. Just sit to the side of them and be amazed by the problems that arise. At least you are there to help them out when they are stuck. You can adjust your tutorial accardingly.
Thanks for this Jesse, I’m about to write tutorials on-mass, it’s good to have guidelines such as these.
Speaking of “one-way communication”: That’s a major problem and I think we should go deeper with this. I see the problem is no with the writer alone but also with the readers. I write blog articles, tutorials and demos myself and what’s always bugging me is the lack of feedback! What happens? If someone reads an article and it helps him – he is satisfied and usually just walks away. Sometimes he leaves a “thank you for this (put adjective here) article”. if it does not help him he gets frustrated, just leaves and maybe never comes back.
So we all could get along much better if we make it a two-way communcation. Don’t walk away in anger but instead tell me how and what I can do to make my article(s) better. The result would be winners on both sides!
I agree with you in most aspects. Good work but I have two questions:
1. How do you identify the audience? If you talk about knowledge levels, there’s no clear line between beginner, intemediate and pro. Morover these definitions are pretty subjective.
2. at #10 you wrote, “…translating from your demo directly to my problem”.
How should a writer know what “your” problem is? An article/blog entry/Demo/Tutorial is always a one-way communication. The only way I see is to keep the tutorial (or whatever) in a general style and there we are back again with “foo”. However “Foo” is a cause for confusion many times because it’s simply too abstract and it can obscure the meaning behind (at least) a certain part of the code. OK I could come up with a real world example but is it suitable for your actual problem domain? How can I (the writer) help you to get your mind in consonance to mine?
Please let me make this clear: I don’t want to criticize your work but I see these problems with it.