PragDave: SYWTWAB 3: The Hero's Journey: Are You Experienced?

Snap_027

Listen to this blog post courtesy of the Rails Tumblecast

Ajax
This is the third of a series of personal notes to people who may be thinking of writing (or who have embarked upon writing) a book. You'll be able to find them all (eventually) by selecting the tag Writing A Book.

In the last post on writing we looked at the idea that a technical book can have a narrative, and that a good book will allow the reader to identify with the hero of that narrative.

However, there's more to this narrative business that just girding your loins, sharpening your blade, and traipsing off after dragons. You also have to allow your hero to develop. A hero starts off uncertain, and will take whatever small victories that she or he can take. As the hero gains confidence, she'll start to take on bigger (and often more ambiguous) foes. Battles will use more dexterity and wits, and less brute strength.

In technical writing, this gaining of experience is explained by the Dreyfus Model of Skills Acquisition.

Andy and I were introduced to this concept by Andy's wife. At that time she was a nurse practitioner. One of the core books during her education was From Novice to Expert by Patricia Benner. This book used a psychological model developed by the Dreyfus brothers to explain the process by which people gain experience when learning a new skill. Before Dreyfus, it was assumed that gaining experience was a bit like filling the gas tank in your car: your brain starts out empty and, as you pour information in through your eyes and ears, the experience dial gradually creeps up.

The Dreyfus brothers showed that this is not the case. They demonstrated that people pass through different levels as they become experienced. Each level has different characteristics. At the early levels, people don't want lots of theory and can't tolerate ambiguity. They want to be told what to do to achieve a goal, and they want to see lots of short-term successes. (If you're about to jump out of a plane for the first time, you're probably more interested in which handle you pull, and when, than in the history and philosophy of skydiving). However, as you gain experience, your needs change. You start needing to put information into a broader context, and to apply it in your own way. You become less rules based, and more intuitive. (This is why really experienced developers often talk to each other using metaphors—the ambiguityand imagery in a metaphor allows them to communicate nuances better).

Not surprisingly, these ideas are crucial to understand when plotting your technical book. Your reader starts out inexperienced when it comes to the content of your book. That's why it is always a mistake to start out with a chapter listing the history of your technology, the philosophy of the design, the quirks of the inventors, and other worthy, tedious topics. At this point, the reader doesn't give a toss about any of it. Instead, they want to know: what can I do? Now?

Start your book with simple examples. Make them interesting (and probably a little humorous to help break the tension) but make the examples relevant. Make you readers feel as if they are achieving something as they work through each. You can use your technology's jargon, but use it sparingly, and only to explain what it means. If you have exercises, make them follow the same pattern; early exercises should be simple, with a single, well-understood point. They should take 15–20 minutes to complete, and it should be obvious to the reader when they've succeeded.

As the book progresses, ramp up the challenges. The text can start to make assumptions about the reader's level of experience—after all, the preceding chapters of the book have helped them gain that experience. You can start to make the descriptions broader, and the challenges more open ended. This is a good time to start using the technology's jargon in context. (If you do this, it doesn't hurt to reinforce the definitions every now and then in a subtle way: “Remember how we described the way that singleton methods are specific to a particular object? That is reflected in the way we define them…”) Exercises can be more open ended, perhaps with no particular correct answer. The pace can pick up.

By the end of the book, your tone becomes collegial. Your reader is becoming your peer, and you can start treating them that way. Their graduation from the book is an invitation to join your world.

The Dreyfus model contains nothing revolutionary. Instead, it describes an evolution—the evolution from novice to expert. This is another aspect of the hero's journey your reader will take.