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?