Writing engaging tutorials

Loading...

Flash Player 9 (or above) is needed to view presentations.
We have detected that you do not have it on your computer. To install it, go here.

0 comments

Post a comment

    Post a comment
    Embed Video
    Edit your comment Cancel

    5 Favorites & 2 Groups

    Writing engaging tutorials - Presentation Transcript

    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/
    2. There is no perfect tutorial.
    3. … as there is no “one” audience.
    4. One thing to keep in mind is the perceived speed of the internet and the impatience of developers.
    5. 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.
    6. Developers work with the IKEA model when using code that is not theirs:
    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.
    9. Readers I encountered:
    10. Readers I encountered: – Give me all the information, I find what I need.
    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.
    13. Readers I encountered:
    14. Readers I encountered: – I need something to copy + paste and get on with it myself
    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.
    17. Catering for them all is tricky.
    18. However, readers are not Pokemons – you don’t need to catch them all.
    19. Start with the basics
    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.
    29. Offer landmarks
    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.
    33. Language
    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…”
    40. Credibility
    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
    45. Leaving them hungry
    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.
    53. Maintenance
    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.
    62. THANKS! http://wait-till-i.com chris.heilmann@gmail.com

    + Christian HeilmannChristian Heilmann, 2 years ago

    custom

    4199 views, 5 favs, 3 embeds more stats

    My final talk at the Yahoo! Frontend Engineering su more

    More info about this document

    CC Attribution-ShareAlike LicenseCC Attribution-ShareAlike License

    Go to text version

    • Total Views 4199
      • 4127 on SlideShare
      • 72 from embeds
    • Comments 0
    • Favorites 5
    • Downloads 89
    Most viewed embeds
    • 38 views on http://packtdavidb.tumblr.com
    • 33 views on http://icant.co.uk
    • 1 views on http://www.wait-till-i.com

    more

    All embeds
    • 38 views on http://packtdavidb.tumblr.com
    • 33 views on http://icant.co.uk
    • 1 views on http://www.wait-till-i.com

    less

    Flagged as inappropriate Flag as inappropriate
    Flag as inappropriate

    Select your reason for flagging this presentation as inappropriate. If needed, use the feedback form to let us know more details.

    Cancel
    File a copyright complaint
    Having problems? Go to our helpdesk?

    Categories