My final talk at the Yahoo! Frontend Engineering summit in London. This is a presentation containing tips and ideas about how you can write successful, engaging tutorials for online use.
COMPUTER 10: Lesson 7 - File Storage and Online Collaboration
Writing engaging tutorials
1. 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/
7. Developers work with the
IKEA model when using code
that is not theirs:
Open it, mess around, start
reading when you get stuck.
8. 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.
11. Readers I encountered:
– Give me all the information, I find
what I need.
– Get me a step-by-step instruction
how to do things
12. 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.
15. Readers I encountered:
– I need something to copy + paste
and get on with it myself
– I don’t get it, can you show me?
16. 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.
20. 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.
21. 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.
22. 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.
23. 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.
24. 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.
25. 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.
26. 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.
27. 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.
28. 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.
30. 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.
31. 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.
32. 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.
34. 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…”
35. 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…”
36. 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…”
37. 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…”
38. 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…”
39. 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…”
41. 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>
42. 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>
43. 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>
44. 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
46. 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)
47. 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)
48. 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)
49. 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.
50. 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.
51. 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.
52. 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.
54. 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.
55. 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.
56. 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.
57. 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.
58. 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.
59. 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.
60. 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.
61. 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.