Writing engaging tutorials
Making them come back for more
Christian Heilmann
Yahoo! Frontend Engineering Summit UK
December 2007
http://creativecommons.org/licenses/by-sa/3.0/

There is no perfect tutorial.

… as there is no “one”
audience.

One thing to keep in mind is
the perceived speed of the
internet and the impatience of
developers.

We are much more patient
when it comes to assembling
a plumbing unit in our flat
than when it comes to using
other people’s code.

Developers work with the
IKEA model when using code
that is not theirs:

Developers work with the
IKEA model when using code
that is not theirs:
Open it, mess around, start
reading when you get stuck.

Developers work with the
IKEA model when using code
that is not theirs:
Open it, mess around, start
reading when you get stuck.
Complain when you find a
channel that answers.

Readers I encountered:

Readers I encountered:
– Give me all the information, I find
what I need.

Readers I encountered:
– Give me all the information, I find
what I need.
– Get me a step-by-step instruction
how to do things

Readers I encountered:
– Give me all the information, I find
what I need.
– Get me a step-by-step instruction
how to do things
– I want to click on things and see
how they work, then read.

Readers I encountered:

Readers I encountered:
– I need something to copy + paste
and get on with it myself

Readers I encountered:
– I need something to copy + paste
and get on with it myself
– I don’t get it, can you show me?

Readers I encountered:
– I need something to copy + paste
and get on with it myself
– I don’t get it, can you show me?
– Doesn’t work for me, I know better
and this never worked in my
professional environment.

Catering for them all is tricky.

However, readers are not
Pokemons – you don’t need
to catch them all.

Start with the basics

Start with the basics
– Why is this a good idea
– Which real-life day to day web
development problem is solved by it.
– What is the level of this tutorial – what
do you need to know.
– Show a prominent link to a working
example – if there is a visual outcome
use a linked screenshot.

Start with the basics
– Why is this a good idea
– Which real-life day to day web
development problem is solved by it.
– What is the level of this tutorial – what
do you need to know.
– Show a prominent link to a working
example – if there is a visual outcome
use a linked screenshot.

Start with the basics
– Why is this a good idea
– Which real-life day to day web
development problem is solved by it.
– What is the level of this tutorial – what
do you need to know.
– Show a prominent link to a working
example – if there is a visual outcome
use a linked screenshot.

Start with the basics
– Why is this a good idea
– Which real-life day to day web
development problem is solved by it.
– What is the level of this tutorial – what
do you need to know.
– Show a prominent link to a working
example – if there is a visual outcome
use a linked screenshot.

Start with the basics
– Offer links to full documentation
elsewhere (W3C, MSDN, YDN)
– Offer the download package with code
examples or image templates upfront.
– Give an estimate as to how long it
should take to go through this tutorial.
– Say your name, a way to contact you
and when you wrote this.

Start with the basics
– Offer links to full documentation
elsewhere (W3C, MSDN, YDN)
– Offer the download package with code
examples or image templates upfront.
– Give an estimate as to how long it
should take to go through this tutorial.
– Say your name, a way to contact you
and when you wrote this.

Start with the basics
– Offer links to full documentation
elsewhere (W3C, MSDN, YDN)
– Offer the download package with code
examples or image templates upfront.
– Give an estimate as to how long it
should take to go through this tutorial.
– Say your name, a way to contact you
and when you wrote this.

Start with the basics
– Offer links to full documentation
elsewhere (W3C, MSDN, YDN)
– Offer the download package with code
examples or image templates upfront.
– Give an estimate as to how long it
should take to go through this tutorial.
– Say your name, a way to contact you
and when you wrote this.

Start with the basics
– Offer links to full documentation
elsewhere (W3C, MSDN, YDN)
– Offer the download package with code
examples or image templates upfront.
– Give an estimate as to how long it
should take to go through this tutorial.
– Say your name, a way to contact you
and when you wrote this.

Offer landmarks

Offer landmarks
– Offer a “quick jump / table of contents”
feature – this also allows bookmarking
– Cut the tutorial up into logical steps /
units with useful headings (don’t try to
be funny)
– Add a link to the state of the code at
each step – so people can follow the
changes without needing to copy and
paste.

Offer landmarks
– Offer a “quick jump / table of contents”
feature – this also allows bookmarking
– Cut the tutorial up into logical steps /
units with useful headings (don’t try to
be funny)
– Add a link to the state of the code at
each step – so people can follow the
changes without needing to copy and
paste.

Offer landmarks
– Offer a “quick jump / table of contents”
feature – this also allows bookmarking
– Cut the tutorial up into logical steps /
units with useful headings (don’t try to
be funny)
– Add a link to the state of the code at
each step – so people can follow the
changes without needing to copy and
paste.

Language

Language
– PBE - Plain Bloody English
– Explain your TLAs
– Explain product names and special
terms
– Use short sentences.
– Avoid the “I”, instead invite the reader
with a “then you can do…” or a “Let’s…”

Language
– PBE - Plain Bloody English
– Explain your TLAs
– Explain product names and special
terms
– Use short sentences.
– Avoid the “I”, instead invite the reader
with a “then you can do…” or a “Let’s…”

Language
– PBE - Plain Bloody English
– Explain your TLAs
– Explain product names and special
terms
– Use short sentences.
– Avoid the “I”, instead invite the reader
with a “then you can do…” or a “Let’s…”

Language
– PBE - Plain Bloody English
– Explain your TLAs
– Explain product names and special
terms
– Use short sentences.
– Avoid the “I”, instead invite the reader
with a “then you can do…” or a “Let’s…”

Language
– PBE - Plain Bloody English
– Explain your TLAs
– Explain product names and special
terms
– Use short sentences.
– Avoid the “I”, instead invite the reader
with a “then you can do…” or a “Let’s…”

Language
– PBE - Plain Bloody English
– Explain your TLAs
– Explain product names and special
terms
– Use short sentences.
– Avoid the “I” - instead invite the reader
with a “then you can do…” or a “Let’s…”

Credibility

Credibility
– Back up your statements with examples.
– Back up your statements with third party
resources.
– Never hush up errors you made. If
feedback changes your tutorial, thank
the commenter and add the changes.
<del>/<ins>

Credibility
– Back up your statements with examples.
– Back up your statements with third party
resources.
– Never hush up errors you made. If
feedback changes your tutorial, thank
the commenter and add the changes.
<del>/<ins>

Credibility
– Back up your statements with examples.
– Back up your statements with third party
resources.
– Never hush up errors you made. If
feedback changes your tutorial, thank
the commenter and add the changes.
<del>/<ins>

Credibility
– Back up your statements with examples.
– Back up your statements with third party
resources.
– Never hush up errors you made. If
feedback changes your tutorial, thank
the commenter and add the changes.
<del>/<ins>
– Have an editor / reviewer

Leaving them hungry

Leaving them hungry
– Offer extra problems / other application
ideas at the end and let people try them
out.
– Hint at more tricks in the same vain or
link to other tutorials.
– Show high-class solutions using that
trick (which awesome sites use it)

Leaving them hungry
– Offer extra problems / other application
ideas at the end and let people try them
out.
– Hint at more tricks in the same vain or
link to other tutorials.
– Show high-class solutions using that
trick (which awesome sites use it)

Leaving them hungry
– Offer extra problems / other application
ideas at the end and let people try them
out.
– Hint at more tricks in the same vain or
link to other tutorials.
– Show high-class solutions using that
trick (which awesome sites use it)

Traps to avoid!
– Don’t offer the solutions to code
exercises, people will only copy + paste
and learn nothing.
– Don’t cut up code into non-executable
chunks, show the whole script then
repeat the parts bit-by-bit.
– Stick to one solution per tutorial and
explain this one well.

Traps to avoid!
– Don’t offer the solutions to code
exercises, people will only copy + paste
and learn nothing.
– Don’t cut up code into non-executable
chunks, show the whole script then
repeat the parts bit-by-bit.
– Stick to one solution per tutorial and
explain this one well.

Traps to avoid!
– Don’t offer the solutions to code
exercises, people will only copy + paste
and learn nothing.
– Don’t cut up code into non-executable
chunks, show the whole script then
repeat the parts bit-by-bit.
– Stick to one solution per tutorial and
explain this one well.

Traps to avoid!
– Don’t offer the solutions to code
exercises, people will only copy + paste
and learn nothing.
– Don’t cut up code into non-executable
chunks, show the whole script then
repeat the parts bit-by-bit.
– Stick to one solution per tutorial and
explain this one well.

Maintenance

Maintenance
– Don’t leave your tutorials to collect
dust.
– If they become outdated, find a
better, up-to-date solution and link
or even redirect to this one.
– We have more than enough
information graveyards.

Maintenance
– Don’t leave your tutorials to collect
dust.
– If they become outdated, find a
better, up-to-date solution and link
or even redirect to this one.
– We have more than enough
information graveyards.

Maintenance
– Don’t leave your tutorials to collect
dust.
– If they become outdated, find a
better, up-to-date solution and link
or even redirect to this one.
– We have more than enough
information graveyards.

What are you in for?
– Last but not least, it is not about
you!
– You will get positive and negative
comments targeted at you and not
the subject.
– Don’t take any of these serious.
– Most of your readers will never
contact you or take part.

What are you in for?
– Last but not least, it is not about
you!
– You will get positive and negative
comments targeted at you and not
the subject.
– Don’t take any of these serious.
– Most of your readers will never
contact you or take part.

What are you in for?
– Last but not least, it is not about
you!
– You will get positive and negative
comments targeted at you and not
the subject.
– Don’t take any of these serious.
– Most of your readers will never
contact you or take part.

What are you in for?
– Last but not least, it is not about
you!
– You will get positive and negative
comments targeted at you and not
the subject.
– Don’t take any of these serious.
– Most of your readers will never
contact you or take part.

What are you in for?
– Last but not least, it is not about
you!
– You will get positive and negative
comments targeted at you and not
the subject.
– Don’t take any of these serious.
– Most of your readers will never
contact you or take part.

THANKS!
http://wait-till-i.com
chris.heilmann@gmail.com