Upgrade to Pro — share decks privately, control downloads, hide ads and more …

The Unenviable Tutorial

The Unenviable Tutorial

It's the first thing every new user looks for, the raison d'être of every project, almost always will completely divide the people evaluating your software & is the leading cause of liver cancer in the American pub... wait, no. Forget that last part. What I'm talking about is the Tutorial.

Frequently the first bit of documentation written, the first one to fall hopelessly out of date & the one *everyone* sees, the Tutorial bears the brunt of getting people started. Its job is to pull people in. It teaches them not only what the software is about, but *how* it should be used. It sets the stage, the standard & the lowest bar of entry. It's unenviable because it must do so many things & do them well to be a success.

daniellindsley

April 08, 2013
Tweet

More Decks by daniellindsley

Other Decks in Technology

Transcript

  1. The Unenviable
    Tutorial

    View full-size slide

  2. Who?
    • Daniel Lindsley
    • Author of several decently-used Python/
    Django libraries
    • ...which pride themselves on good docs
    * I believe docs make all the difference in initial adoption of software.
    * Things that are terrible but have good docs make better traction than good software
    without.

    View full-size slide

  3. What makes the
    Tutorial
    “Unenviable”?
    * Why would you describe a tutorial this way? Why such a strong word?
    * I really believe the tutorial has the worst job in any collection of docs.

    View full-size slide

  4. Unenviable
    Qualities
    • The first doc everyone sees
    * And because people are people, they’re going to make snap judgements based off just the
    tutorial. It’s going to happen.

    View full-size slide

  5. Unenviable
    Qualities
    • The first doc everyone sees
    • Commonly the first doc written
    * Even worse, it’s likely the first documentation you’re going to write & the first to get out of
    date (because you likely NEVER refer to it yourself).
    * Software evolves fast, sometimes out-pacing your ability to document.

    View full-size slide

  6. Unenviable
    Qualities
    • The first doc everyone sees
    • Commonly the first doc written
    • Must pull users in to be effective
    * It’s also a form of marketing material.
    * You have to tell them why it’s important, what features it has & why it’ll make their life
    easier.

    View full-size slide

  7. Unenviable
    Qualities
    • The first doc everyone sees
    • Commonly the first doc written
    • Must pull users in to be effective
    • Sets the standard
    * You’re teaching people what you think good usage of your code looks like.
    * Be warned that some people may be very green & your code may shape how they write
    things in the future.

    View full-size slide

  8. Unenviable
    Qualities
    • The first doc everyone sees
    • Commonly the first doc written
    • Must pull users in to be effective
    • Sets the standard
    • Sets the tone
    * This is a bit more nebulous, but effectively, you’re setting expectations.
    * About how conversational the docs will be.
    * About how the other documentation should look/read.

    View full-size slide

  9. Unenviable
    Qualities
    • The first doc everyone sees
    • Commonly the first doc written
    • Must pull users in to be effective
    • Sets the standard
    • Sets the tone
    • Describe enough but not too much
    * Back to marketing - You gotta sell them on using it.
    * But if you drown them, no one lives to tell the tale.

    View full-size slide

  10. In short, it must be
    everything to
    everyone.
    * At least initially anyway.
    * Holycrapughmonumentaltask.

    View full-size slide

  11. What not to do...
    * Let’s start simple & talk about what the tutorial shouldn’t be.
    * You see this in other projects all the time.
    * It can be very obvious/painful when you see it in others.

    View full-size slide

  12. What not to do...
    • R.A.D. - README as Docs
    * READMEs ARE NOT ENOUGH!
    * Unless your software is stupidly simple & narrow, it’s not enough.
    * READMEs include other things a tutorial shouldn’t (author, license, changelog, etc).

    View full-size slide

  13. What not to do...
    • R.A.D. - README as Docs
    • Show off every single feature
    * This is what API docs that cover method by method are for. Don’t do this.

    View full-size slide

  14. What not to do...
    • R.A.D. - README as Docs
    • Show off every single feature
    • Immediately deep-dive into the specialty
    portions of the tech
    * Your software solves a problem.
    * Chances are the user doesn’t want to know the intricacies, otherwise they’d’ve built their
    own library.

    View full-size slide

  15. What not to do...
    • R.A.D. - README as Docs
    • Show off every single feature
    • Immediately deep-dive into the specialty
    portions of the tech
    • Write just for the advanced user
    * You’re the advanced user. You know more about the software than anyone else.
    * Hence, you’re already out of the audience for the document.
    * It’s easy to miss things or gloss over things that need more explanation.
    * Be vigilant.

    View full-size slide

  16. * So, with the bad stuff in mind, how to do we go about building the tutorial the right way?

    View full-size slide

  17. Considerations for
    the Tutorial
    * Let’s start with what we should be thinking about.
    * Then later we’ll dive into how to approach/organize it.

    View full-size slide

  18. Considerations
    • Both the novice & pros will land there
    * Remember, this is the first doc *everyone* will see, regardless of skill level or familiarity.

    View full-size slide

  19. Considerations
    • Both the novice & pros will land there
    • It must prove the software’s worth
    * It’s not just showing examples, you have to describe why it’s worthwhile.
    * Example: an API framework that can serialize the data into any format requested. Easy to
    build a single serialization format yourself, much more complex to be flexible.

    View full-size slide

  20. Considerations
    • Both the novice & pros will land there
    • It must prove the software’s worth
    • “Lunch hour”-able
    * The idea is that someone can work through your whole tutorial alone within an hour & have
    something functional.
    * High power-to-weight ratio.

    View full-size slide

  21. Considerations
    • Both the novice & pros will land there
    • It must prove the software’s worth
    • “Lunch hour”-able
    • Leave them wanting more
    * The point of the tutorial is to be an introduction, to familiarize the user with the core
    concepts & the usage.
    * Keeping yourself in check & establishing a good breaking point is difficult.

    View full-size slide

  22. * With those things in mind, ...

    View full-size slide

  23. How to construct
    the Tutorial
    * The next phase is to actually start building the tutorial.
    * What follows are the things I try to keep in mind while actually writing the doc.
    * I’m not going to tell you what to write.

    View full-size slide

  24. 1. Pick the easiest-
    to-bite-off features
    K. I. S. SillyPants
    * This is a great way to show off the “porcelain”, the conveniences, the easiest way to get
    things done.
    * Highest power-to-weight ratio APIs

    View full-size slide

  25. 2. Start simple
    Minimum Viable...
    * Hate that term, so jump quickly through this & the next slide.

    View full-size slide

  26. 2. Start simple
    Minimum Viable...
    * JUMP!

    View full-size slide

  27. 2. Start simple
    Minimum Viable...
    Enough to get something working fast
    * It’s gotta be simple, or as simple as possible to start with.
    * Again, this tends to be the high-level APIs, the ones that make lots of assumptions & cover
    the 80% cases well.

    View full-size slide

  28. 3. Small iterations
    Build on what you’ve already taught them.
    * Your examples should shoot for a dozen or so lines (dynamic languages anyhow).
    * Show ways to expand on what they’ve already learned, how to change options or behavior
    to be slightly more advanced.

    View full-size slide

  29. 4. Friendly prose
    Speak simply & clearly.
    Expand on new/difficult concepts.
    * Write the docs the way you’d want to read someone else’s docs.
    * Stuffy language, excessive terminology/jargon & “distant” writing are ways you turn off the
    user.
    * A conversational tone can go a long way.

    View full-size slide

  30. 5. Write for the
    newbie
    But make it easy for the advanced user
    to skim yet absorb.
    * Assume as little as you can, within reason, about your audience.
    * Personal story - “I just started with language X yesterday & am trying to use...”
    * Advanced users will land here frequently as well, so while you shouldn’t write for them
    alone, making it easy for them to extract just what they need is crucial.

    View full-size slide

  31. 6. Know when to
    stop
    At some point, in-depth guides & API docs
    should take over.
    * It’s enough to get them running.
    * A good indicator is when you start to stray from the 80% case.
    * Other guides can more exhaustively cover the advanced bits.

    View full-size slide

  32. Common pitfalls
    * Let’s talk about some pitfalls I’ve encountered, both in other people’s tutorials as well as
    my own docs.

    View full-size slide

  33. Common pitfalls
    • Making assumptions
    * We’ve already covered this a bit, but it bites me all the time.
    * A good coping device is to have someone who doesn’t even work in tech read through &
    see what doesn’t make enough sense for them.

    View full-size slide

  34. Common pitfalls
    • Making assumptions
    • Diving too deep too quickly
    * If you force too much on them too quickly & without enough explanation, people are going
    to gloss over.
    * The negative reaction may mean they look for other libraries or tell others bad/incorrect
    things about your software. (Anecdote - Happens with Tastypie all the time re: models.)

    View full-size slide

  35. Common pitfalls
    • Making assumptions
    • Diving too deep too quickly
    • Not showing enough (!)
    * The flip side of that coin is not showing enough.
    * Go too shallow & it may look like your software can’t do what the user needs.
    * Most users won’t source-dive to start with, so make sure you talk about what it can do.

    View full-size slide

  36. Common pitfalls
    • Making assumptions
    • Diving too deep too quickly
    • Not showing enough (!)
    • All examples, no explanatory prose
    * If all you show are just a bunch of examples, you’re left with a disjointed doc that has no
    flow & will leave some users confused.
    * Anecdote - I’m guilty. Happened to me with a microframework (itty) of mine.
    * Some people just want to see how it’s used, others need the “why”.

    View full-size slide

  37. Common pitfalls
    • Making assumptions
    • Diving too deep too quickly
    • Not showing enough (!)
    • All examples, no explanatory prose
    • Leaving the user hanging at the end
    * Once you’ve shown them how to get started, give them a headstart on places they’re likely
    to need next.
    * A lost user will struggle & subsequently generate both a lot more support requests as well
    as be grumpier about the experience.

    View full-size slide

  38. Now what‽
    • Now it’s time for the guides
    * If you started with the tutorial, now’s the time to start writing the deeper dive portions,
    where you focus on a certain part of the tech or on a certain concept.
    * Think of them as advanced forms of the tutorial.

    View full-size slide

  39. Now what‽
    • Now it’s time for the guides
    • Links, links everywhere!
    * Unless you’re printing on paper, you have no excuse not to have links everywhere.
    * This is a great way to demonstrate capability & lead the user to what they need without
    bloating the tutorial.

    View full-size slide

  40. Now what‽
    • Now it’s time for the guides
    • Links, links everywhere!
    • Peer-review: Run it past friends/coworkers
    * Self-explanatory.
    * The more eyes the better.
    * Try walking through yourself with NewbieGlasses™ on.

    View full-size slide

  41. Now what‽
    • Now it’s time for the guides
    • Links, links everywhere!
    • Peer-review: Run it past friends/coworkers
    • Make sure help channels are available
    * Make sure either your tutorial or README (preferably both) give the user ways to get help
    from others, ways to report bugs & ways to talk about the software.
    * This draws them into the broader community.

    View full-size slide

  42. Thanks!
    @daniellindsley
    https://github.com/toastdriven
    * FIN

    View full-size slide