The Unenviable Tutorial

Slide 1

Slide 1 text

Slide 2

Slide 2 text

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.

Slide 3

Slide 3 text

No content

Slide 4

Slide 4 text

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.

Slide 5

Slide 5 text

Unenviable Qualities • The ﬁrst 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.

Slide 6

Slide 6 text

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.

Slide 7

Slide 7 text

Unenviable Qualities • The ﬁrst doc everyone sees • Commonly the ﬁrst 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.

Slide 8

Slide 8 text

Unenviable Qualities • The ﬁrst doc everyone sees • Commonly the ﬁrst 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.

Slide 9

Slide 9 text

Unenviable Qualities • The ﬁrst doc everyone sees • Commonly the ﬁrst 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.

Slide 10

Slide 10 text

Unenviable Qualities • The ﬁrst doc everyone sees • Commonly the ﬁrst 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.

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

No content

Slide 13

Slide 13 text

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.

Slide 14

Slide 14 text

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).

Slide 15

Slide 15 text

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.

Slide 16

Slide 16 text

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.

Slide 17

Slide 17 text

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.

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

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.

Slide 20

Slide 20 text

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

Slide 21

Slide 21 text

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 ﬂexible.

Slide 22

Slide 22 text

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.

Slide 23

Slide 23 text

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.

Slide 24

Slide 24 text

* With those things in mind, ...

Slide 25

Slide 25 text

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.

Slide 26

Slide 26 text

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

Slide 27

Slide 27 text

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

Slide 28

Slide 28 text

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

Slide 29

Slide 29 text

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.

Slide 30

Slide 30 text

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.

Slide 31

Slide 31 text

4. Friendly prose Speak simply & clearly. Expand on new/difﬁcult 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.

Slide 32

Slide 32 text

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.

Slide 33

Slide 33 text

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.

Slide 34

Slide 34 text

No content

Slide 35

Slide 35 text

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

Slide 36

Slide 36 text

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.

Slide 37

Slide 37 text

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.)

Slide 38

Slide 38 text

Common pitfalls • Making assumptions • Diving too deep too quickly • Not showing enough (!) * The ﬂip 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.

Slide 39

Slide 39 text

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 ﬂow & 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”.

Slide 40

Slide 40 text

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.

Slide 41

Slide 41 text

No content

Slide 42

Slide 42 text

Now what‽

Slide 43

Slide 43 text

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.

Slide 44

Slide 44 text

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.

Slide 45

Slide 45 text

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.

Slide 46

Slide 46 text

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.