Learn Enough Tutorial Writing to Be Dangerous

by Michael Hartl

The video titled 'Learn Enough Tutorial Writing to Be Dangerous' presented by Michael Hartl during the LA RubyConf 2015 focuses on effective tutorial writing techniques that leverage storytelling in technical narratives. Hartl, known for his work on the Ruby on Rails tutorial, provides insight into creating engaging instructional content aimed particularly at beginners. The talk centers around several key principles and methods to enhance the tutorial writing process.

Key Points Discussed:

Understanding Motivations: Hartl emphasizes the importance of understanding the motivation behind each section of a tutorial to keep both the writer and the learner engaged.
Structure is Key: Effective tutorials have a well-thought-out structure that feels seamless to the reader. Knowing what to cover and when is a critical part of tutorial writing, helping to avoid overwhelming the student.
Deferring Material: Rather than explaining every concept upfront, Hartl advises deferring complex material for later, allowing readers to grasp fundamental ideas first without getting stuck on details.
Use of Concrete Examples: He advocates beginning with concrete examples prior to abstract concepts to facilitate better understanding, making tutorials more accessible for beginners.
Repetition and the Spiral Method: Repeating key concepts through varied examples reinforces learning, helping students to better retain information.
Process of Successive Refinement: Hartl shares a five-step process for writing tutorials which includes free association, content outlining, exposition, polishing, and iterating based on feedback to ultimately refine the content into a coherent tutorial.
Visual Aids and Authorial Voice: Incorporating visual elements and maintaining a consistent authorial tone throughout the tutorial are highlighted as effective techniques to enhance learner engagement.
Finality is an Illusion: Hartl encourages writers to understand that tutorial writing is an ongoing process; there’s always room for improvement and feedback is essential for evolution.

In conclusion, Hartl’s final takeaway stresses the importance of shipping quality educational content while iterating based on learner feedback. He encourages aspiring tutorial writers to adopt a narrative-driven approach, emphasizing both clarity and engagement in their instructional materials. This philosophy not only aids the learner's understanding but enriches the overall experience of learning technical skills. His work, including upcoming tutorials under the 'Learning Enough' brand, aims to bridge the gap for complete beginners eager to dive into technical subjects.

00:00:06.000 So, good morning everyone. I just want to first say that I'm a local. If you didn't know, I live in Pasadena, and this is Pasadena City Hall.

00:00:09.000 Boston is also the home of the Rose Bowl, the Rose Parade, Caltech, and technically JPL. JPL is actually mostly in La Cañada Flintridge, but they maintain a Pasadena address for branding purposes. I'm really happy to be out here today supporting the local Los Angeles Ruby community. My name is Michael Hartl, and I'm here to talk to you about 'Learn Enough Tutorial Writing to Be Dangerous.'

00:00:47.440 I'm guessing some of you know me as the author of the Ruby on Rails tutorial. Just to get a quick sense of it, how many people here have read the Rails tutorial or have done so? Okay, so most people here know the Rails tutorial, cool. Some of you may also know me for something else that's instructive, which is actually designed as a tutorial but has a different tone. It's called 'The Town Manifesto.' I see you over there, Ryan, I know Ryan back there. Are any of the Tallis in the audience? Yes? All right, so this is an anti-pi mathematical essay. But I'm actually working on some more tutorials now.

00:01:30.880 The talk you're seeing today is a meta talk about a brand called 'Learning Enough to Be Dangerous.' This is inspired by Zed Shaw's 'Learn Code The Hard Way' brand, and it's meta because it also manages expectations. You can't do 'Learn Python The Hard Way' and then complain that it was hard. Similarly, you can't do a 'Learn Enough to Be Dangerous' tutorial and then complain that it didn't cover everything about it. The first one is a command line tutorial which would actually serve as a good prerequisite for the talk we just saw. Coincidentally, it also uses one of its text file examples: a list of all of Shakespeare's sonnets.

00:02:09.759 This just launched last week, the final version of it, and it's part of a series of Learning Enough tutorials designed as prerequisites to the Rails Tutorial. A lot of people ask me if the Rails Tutorial is good for complete beginners, and the answer is not really; it's not designed for that. It's a little too hard. However, people use it that way anyway, and in the entrepreneurial game, that's called a proxy for demand, which means that people actually want this material, thus I'm making it.

00:02:57.840 We started off with the command line, and then it’s going to go through text editors, literally assuming no background except for the ability to open an application. This tutorial is actually aimed at complete beginners. All of this happens under the general umbrella of a company that I've co-founded with a couple of friends called Softcover, which is a publishing platform for technical authors. It powers the Rails tutorial, the Town Manifesto, and these Learning Enough tutorials.

00:03:40.800 I mention this now specifically because I'm working with one of my co-founders on the HTML and CSS tutorials, and I wanted them to know what I do when I write tutorials—what my process is. So I wrote a meta-tutorial called 'Learn Enough Tutorial Writing to Be Dangerous,' which forms the foundation of the talk I'm giving today. This is available online, and I will mention a link at the end of the talk.

00:04:11.360 My approach to tutorials is grounded in something that's very old in human history. Not everyone takes this approach to tutorials, which is part of the reason I'm giving this talk. I hope this will be helpful to those of you who need to produce instructional materials. Everything I do is rooted in story; it is rooted in narrative. The medium I mainly work in is long-form technical narrative. This ancient Greek piece of pottery depicts a scene from the Odyssey. Does anyone recognize it? Yes, this is the scene where Odysseus has his crew chain themselves to the mast so he can listen to the sirens without being lured to his death.

00:05:24.240 Human beings have been learning and retaining information through stories for millennia, probably since we had language. In order to talk about how I build up a story, I want to first discuss some general principles for constructing a good technical narrative and then talk about a specific process of successive refinement for making tutorials. Finally, I will share some miscellaneous tricks of the trade.

00:06:14.080 I'll start off with one of my favorite switches: an adorable baby anteater. It makes me happy just to look at that little guy! I'll mention later on where that comes from. So, let's start with these general principles.

00:07:03.840 There are overarching themes that come from the general way of making stories, and the structure is the most general. Structure—essentially, what goes where, when, and what you cover—is maybe the hardest thing to master because if you do it right, it’s completely invisible. As someone reading a tutorial, you would never know that the structure is good; it just feels like things are flowing.

00:07:25.760 The principles I'm going to give you will help to hack the creation of good structure. One of them is motivation. This doesn't mean your motivation as a writer or the motivation of the student. It means the motivation of the material—why are you doing what you're covering at every moment? You should always know why you're covering that; this also gives rise to better motivation on the part of the student and the author.

00:08:07.360 One of the most general pieces of advice I can give you when writing tutorials is to defer material if you can. This is a very common newbie mistake—to throw everything in and be comprehensive in a treatment that's appropriate for a reference work. However, that's not good for an instructive tutorial. Let me give you an example: this is the implementation of the signup form in the Rails tutorial in the case where the signup fails.

00:08:51.679 If you've built these sorts of signup forms, you probably know that the way you handle the submission in Rails is using what's called strong parameters. However, that’s not necessary at this point in the tutorial, and if you've never studied Rails before, you don’t know what strong parameters are. If it can be deferred, it should be deferred. You'll see a note here that says 'not the final implementation,' and there's a reference forward to a section that actually identifies the subject—in this case, strong parameters.

00:09:48.399 This is a concrete example of deferring something to the future. It’s tempting to say, 'Oh, we'll just cover everything at once,' but that could overwhelm the student. Later on, when you get to the strong parameters, it’s nice to be able to make a back reference and say, 'Remember where we came from.' This process is the main reason my co-founders and I built Softcover—it supports this kind of typesetting and makes it really easy to deploy.

00:10:40.400 Another general principle is to focus on concrete examples first. Human beings are really good at generalizing from examples. It’s tempting to start with abstract examples, but it’s much easier to build up to abstraction through concrete examples. We saw in the previous talk an example of using 'man' and how it’s not designed to instruct, but rather as a reference. This is the 'man' page for 'ls'; 'man' essentially lays out what 'ls' is, but in reality, this is usually what you see.

00:11:51.200 Here’s a concrete example of 'ls -l,' the long form of 'ls,' which shows the dot files. Also consider 'ls -rtl' to list files by time, with the most recently modified files appearing last. This is suggestive because if you look at 'ls' and then the 'rtl,' this is how I discovered the '-h' flag—'human-readable,' where it says, for example, '3.2 gigabytes' instead of a long string of bytes. When constructing concrete examples, it's essential to make them just the right level of difficulty, creating a sense of flow in the reader.

00:12:58.000 Flow is a concept in psychology where you are completely immersed in the moment and lose track of time. One activity that induces flow is rock climbing, where you must find the right balance in difficulty. This 'Goldilocks Principle' means you want your examples to be just right—not too hard and not too easy. To achieve this, imagine what the reader knows at this point in the exposition. Another underrated principle is repetition.

00:14:36.240 Many people think, 'I've already covered that; I don’t want to cover it again,' but if you keep showing examples out of repetition, learners will generalize and reinforce those ideas. This technique is called the spiral method, where you cover the same idea through a series of increasingly difficult examples. Do not be afraid to repeat material; it's beneficial for the learner. Children often watch something repeatedly because they learn new things each time.

00:15:35.440 Now, let’s discuss the actual process I use: a process of successive refinement. This process takes you from the fear of an empty text editor to producing something substantial, like the Rails tutorial, which is 700 pages long. When writing, especially narratives, overcoming the barrier known as 'activation energy' is crucial. If you can get started, you can start rolling and flow as a writer. However, the potential barrier can be challenging.

00:16:25.919 In this context, I like to invoke a principle I learned about in an essay by Paul Graham. He discusses the phenomenon of comb-overs—a gradual process that someone fails to notice. The principle of gradualness is essential in writing and big projects; just doing a little bit regularly can lead you to accomplish significant tasks.

00:17:11.679 So let’s break down the five steps to making one of these tutorials. We start with a 'free association' step. For instance, if I wanted to teach people about Ruby data structures, I would begin by just typing what the subject involves. This is the easiest step—just getting it out of your head. The second hardest step is what I call the 'content throwdown.' After laying out the basic ideas, you then expand on the topic.

00:18:26.640 An example would involve starting off with the topic of hashes. You can block out sections, and while it's not even a complete sentence yet, it’s just a reminder to yourself of what it’s about. Keeping motivation in mind is crucial. For instance, if you’re learning Ruby, you're likely interested in developing web applications, which means understanding hashes is important.

00:19:06.960 Then, start with an empty hash as a note for your future self. You need to defer everything you can at this stage; don’t worry about getting into too much detail. Instead, just throw down ideas on what the content will look like and consider a valuable example. The third step—the main exposition—is the most challenging as it involves explaining what you're teaching. This includes putting strong references to cross-referenced sections in your tutorial.

00:20:02.320 As you work, add cross-references that guide readers throughout. This helps reinforce the material; a broken reference can serve as a reminder for further elaboration. Therefore, proper cross-referencing is like a rug that ties everything together in the tutorial. After the main exposition, the next step consists of a series of polishing passes. This is where I spend lots of time enhancing the work. I can promote something important from an inline code sample to an actual code listing for better clarity.

00:21:11.840 I might refer to significant code listings and ensure each has corresponding cross-references. This step is crucial as it allows me to prepare something polished enough for an audience. Once you have finished polishing your content, distributing it timely is important. You may need to release something like an HTML version of your tutorial chapter beginning, gathering feedback, and continuously refining your piece.

00:22:32.400 After you promote it, don't forget that you must iterate; you're never really done. Eventually, you might create an ebook that requires further promotions through channels like Twitter, Hacker News, and news feeds. Remember that long periods of work are rewarding when you distribute your tutorials successfully.

00:23:16.000 If you manage to create something as big as the Rails tutorial, you will need a break afterward. I know I needed one after working like a madman for six months. But in the end, shipping successfully is rewarding.

00:23:39.600 To wrap up, I'd like to mention several tricks of the trade. One is to include numerous visual aids. People enjoy pictures to supplement the text, such as adorable baby anteaters. Adding something cute can refresh the reader's attention span. This is an approach I learned from Giles Bouguet, which uses human neurology to enhance the learning process.

00:24:29.760 Moreover, tables are vital and very effective. They allow you to summarize information you have made a narrative out of—almost an overview at the end of every section. This produces clear benefits of both a reference and instructive narrative that facilitates the learning process. Despite being a bit fuzzy, it's essential to develop a unique authorial voice.

00:25:23.040 Voice refers to tone, vocabulary, and style when teaching through tutorials. For instance, the Town Manifesto has an edge but maintains an instructive tone. In contrast, the Rails tutorial is friendly and aims for an even tone. Having an even instructional tone allows for humor contrasts, such as inserting playful references without being overly comedic. A common mistake is to try being humorous all the time; realism is key during tough learning moments.

00:26:24.480 Throughout our discussion, we’ve examined general principles, the process of refinement, and some tricks of the trade. Remember, as Steve Jobs said, 'Real artists ship.' When you create tutorial content, you may receive positive feedback that resonates, such as when someone appreciates your hard work or mentions your work as one of their favorites.

00:27:23.440 And if you are lucky, you might even lead to made products that support your life, making room for breaks after extensive labor. I truly recommend French Polynesia if you have the chance. With that, I conclude my talk today; I'm interested in pursuing more advanced tutorials under this brand name. If you're interested, please contact me at learnenough.com.

00:28:17.760 I'd really like to thank LA RubyConf for having me out here today. It’s a pleasure being part of the LA Ruby community. Thanks!

00:29:00.440 Now, I think we should have time for a few questions!