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.

Transcript

1. The Unenviable Tutorial
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.
4. 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.
5. 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.
6. 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.
7. 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.
8. 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.
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 * 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.
10. 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.
11. In short, it must be everything to everyone. * At least initially anyway. * Holycrapughmonumentaltask.
13. 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.
14. 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).
15. 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.
16. 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.
17. 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.
18. * So, with the bad stuff in mind, how to do we go about building the tutorial the right way?
19. 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.
20. Considerations • Both the novice & pros will land there * Remember, this is the first doc *everyone* will see, regardless of skill level or familiarity.
21. 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.
22. 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.
23. 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.
24. * With those things in mind, ...
25. 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.
26. 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
27. 2. Start simple Minimum Viable... * Hate that term, so jump quickly through this & the next slide.
28. 2. Start simple Minimum Viable... * JUMP!
29. 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.
30. 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.
31. 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.
32. 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.
33. 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.
35. Common pitfalls * Let’s talk about some pitfalls I’ve encountered, both in other people’s tutorials as well as my own docs.
36. 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.
37. 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.)
38. 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.
39. 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”.
40. 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.
42. Now what‽
43. 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.
44. 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.
45. 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.
46. 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.
48. Thanks! @daniellindsley https://github.com/toastdriven * FIN