The coolest app you never knew was on your hard drive
If you use OS X, then you own an application that’ll waste hours of your time just sitting on your hard drive.
Say hello to Applications > Utilities > Grapher.
We needed a simple Fourier square wave for a book. Just type in the equations, and out it pops.
But the time wasting comes from playing with its example graphs.
Did I mention that they animate, and it can export Quicktime?
It Starts With Verbs and Nouns
Roy Fielding’s REST work showed us that the design of the interaction between a client and a server could make a major difference to the reliability and scalability of that application. If you follow a set of conventions embodied in REST when designing your application, is means that (for example) the network will be able to cache responses to certain requests, offloading work from both upstream network components and from the application.
But REST was about more than performance. It offered a way of separating the actions performed by your applications (the verbs) from the things acted upon (the nouns, or in REST terms, the resources). What’s more, REST said that the verbs that you use should apply consistently across all your resources.
When using HTTP, the HTTP verbs (such as GET, PUT, POST, and DELETE) are also the verbs that should be used with REST applications. This makes a lot of sense, because things like routers and proxies also understand these verbs.
One of the successes built using these principles is the Atom Publishing Protocol. Atom allows clients to fetch, edit, and publish web resources. Atom is probably most commonly applied to allow people to use local editors to create and maintain blog articles—client software on the user’s computer uses Atom to fetch existing articles and to save back edited or new articles.
Let’s look at how that happens with Atom.
I fire up my Atom-based local client. It needs to fetch the updated list of all the articles currently on the server, so it issues a GET request to a URL that represents the collection of articles: the verb is GET, and the resource is the collection.
GET /articles
What comes back is a list of resources. Included with each resource are one or two URIs. One of these URIs can be used to access that resource for editing. Let’s say I want to edit a particular article. First, my client software will fetch it, using the URI given in the collection:
GET /article/123
As a user of the editing software, I then see a nicely formatted version of the article. If I click the [EDIT]button, that view changes: I now see text boxes, drop down lists, text areas, and so on. I can now change the article’s contents. When I press [SAVE], the local application then packages up the changed article and sends it back to the server using a PUT request. The use of PUT says “update an existing resource with this new stuff.”
Browsers are Dumb
If you use a browser to interact with a server, you’re using a half-duplex, forms-based device. The host sends down a form, you fill in the form, and send it back when you’re ready. This turns out to be really convenient for people running networks and servers. Because HTTP is stateless, and because applications talk to browsers using a fire-and-forget model, your servers and networks can handle very large numbers of devices. This is exactly the architecture that IBM championed back in the 70s. The half-duplex, poll-select nature of 3270-based applications allowed mainframes with less processing power than a modern toaster to handle tens of thousands of simultaneous users. The browser is really not much better than a 3270 (except the resolution is better when displaying porn). (Recently, folks have been trying to circumvent this simplicity by making browser-based applications more interactive using technologies such as Ajax. To my mind, this is just a stop-gap until we throw the browser away altogether—Ajax is just lipstick on a pig.)
How well do browsers play in a RESTful world?
Well, for a start, they really only use two of the HTTP verbs: GET and POST. Is this a problem? Yes and no.
We can always hack around the lack of verbs by embedding the verb that you wanted to use somewhere in the request that you send to the server. It can be embedded in the URL that you use to access a resource or it can be embedded in the body of the request (for example as an element of the POST data). Both work, assuming the server understands the conventions. But both techniques also mean that you’re not using REST and the HTTP verb set; you’re simply using HTTP as a transport with your own protocol layered on top. And that means that the network is less able to do clever things to optimize your traffic.
But a browser talking HTML over HTTP is also lacking in another important area. It isn’t running any application functionality locally. Remember our Atom-based blogging client? It had smarts, and so it knew how to display an article for editing. Browsers don’t have that (without a whole lot of support in terms of bolted on Javascript or Flash). So, as a result, people using RESTful ideas to talk to browsers have to put the smarts back on the server. They invent new URLs which (for example) return a resource, but return it all wrapped up in the HTML needed to display it as a form for browser-based editing. This is how Rails does it. Using the Rails conventions, if I want to fetch an article for viewing on a browser, I can use
GET /article/1
If, instead, I want to allow the user to edit the resource, I issue
GET /article/1;edit
The application then sends down a form pre-populated with the data from that article. When I hit submit, the form contents are sent back to the server, along with a hidden field that tells the server to pretend that the HTTP POST request is actually a RESTful PUT request—the result is that the resource is updated on the server.
The ;xxx notation looks like it was tacked on. I think that in this case, looks aren’t deceiving—these modifiers really were something of an afterthought, added when it became apparent that a pure Atom-like protocol actually wouldn’t do everything needed in a real-world browser-based web application. That’s because the client of an Atom server is assumed to be more that just a display device. An Atom client would not say “fetch me this resource and (oh, by the way) send it down as a form so that I can edit it.” The client would just say GET, do what it had to do, then issue a PUT.
So, in pure REST, the client is a peer (or maybe even in charge) of the interchange. But when talking to a dumb browser, the client is no better than an intermediary between the human and the application. That’s why it was necessary to add things such as ;edit.
Client-independent Applications
One of the other benefits of designing your applications against the limited verbs offered by HTTP REST is that you can (in theory) support many different clients with the same application code. You could write blogging server that (for example) looked at the HTTP Accepts header when deciding what to send back to a client. The response to a GET request to /articles could be a nicely formatted HTML page if the client wants an HTML response, an XML payload if the client asks for XML, or an Atom collection if the client asks for application/atomcoll+xml. In Rails terms, this is handled by therespond_to stanza that is duplicated in each controller action of a RESTful server.
But the benefits run deeper than simply being able to serve up different styles of response.
The HTTP verb set maps (with a little URL tweaking) pretty nicely onto the database verb set. POST, GET, PUT, and DELETE get mapped to the database CRUD verbs: Create, Read, Update, and Delete.
So, in theory at least, you should be able to write your application code as a fairly thin veneer over a set of resources. The application exports the verbs to manipulate the resources and the clients have fun accessing them. This is similar to the vision of Naked Objects.
However, I personally think it was optimistic to try to treat the two styles of interaction (smart and dumb clients) using the same protocol. The ugliness of the ;xxx appendages was a hint.
I think there’s a lot of merit in following a CRUD-based model for interacting with your application’s resources. I’m not convinced all the hassle of bending dumb browser interactions into a REST-based set of verbs, and then extending those verbs to make it work, is worth the extra hassle. To put it another way, I believe the discipline and conventions imposed by thinking of your application interface as a RESTful one are worthwhile. They lead to cleaner and easier-to-understand designs. The hoops you have to jump through to implement it with a browser as a client seem to suggest that a slavish adherence to the protocol might be trying to push it too far.
An Alternative Model
Does that mean I’m down on the RESTful, CRUD based approach to application development? Not at all. For some categories of application, I think it’s a great way of structuring your code. But REST isn’t designed for talking to people. So let’s accept that fact when creating applications. And, while we’re at it, let’s take advantage of the fact that HTTP is such a flexible transport. Rather than trying to design one monolithic application than has both the CRUD functionality and the smarts to be able to talk HTML to end users, why not split it into two smaller and simpler applications?
Put the main application logic into a RESTful server. This is where all the CRUD-style access to resources takes place.
Then, write a second proxy server. This is an HTTP filter, sitting between dumb browsers and your core resources. When browser-based users need to interact with your resources, they actually connect to this proxy. It then talks REST to your main server, and interprets the RESTful responses back into a form that’s useful on the browser. And this filter doesn’t have to be a dumb presentation layer—there’s nothing to say that it can’t handle additional functionality as well. Things like menus, user preferences, and so on could all sit here.
Where does this filter sit? That depends. Sometimes it makes sense to have it running locally on the user’s own computer. In this case you’re back in a situation like the one we looked at with the blogging software. Sometimes it makes sense to have the proxy running on the network. In this case you gain some interesting architectural flexibility—there’s no rule that says you must colocate your REST and presentation servers. Potentially this can lead to better response times, lower network loads, and increased security.
With this approach, we can lose all the hacks we need to make to our URLs and POST data to make them act RESTfully. And we can lose all the ugly respond_to stanzas in our Rails server code. We might even be able to get better reuse, sharing both resource servers and presentation servers between applications.
Let’s call it RADAR. We have a RESTful Application talking to Dumb-Ass Recipients.
Does it work? I don’t know. You tell me.
This is the seventh 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.
Writing a book is an intensely personal thing. You spend hour after hour nurturing it, turning raw words into something you can be proud of. You’ve done your best to convey your message, and to make a book that’s both accurate and entertaining. It’s gorgeous.
It’s really quite a shame that you have to show it to other people.
But you do.
And those other people don’t realize how much work you’re put in, and how subtly you’ve plotted it, and how many ideas you researched. They just want to tell you what’s wrong. That’s their job—they’re reviewers.
Your publisher will have their own policies when it comes to reviewing. Some have a book reviewed chapter by chapter (which seems strange, as good books are not written chapter by chapter). Some review content in chunks. Some wait until the end. And some use a beta-book process, where the general public can subscribe to the book as it is being developed.
Whatever the process, you’ll get reviews. And these can be tough to read. Let’s see how to handle them.
Start by remembering that every review comment is there because someone took the time to write it. The writer hoped to help make your book better. It may be painful, but take every review as something positive.
Each reviewer will have his or her own style, interests, level of experience, and so on. This is just what you want—if your publisher has done its job correctly, your reviewers will be representative of your target audience (with a couple of world experts thrown in to keep your content honest).
Some reviewers may seem to be terribly naive (or even just plain stupid). You’ll find yourself thinking “this guy just doesn’t get it.” And that’s the point. If a reviewer doesn’t get some point, or doesn’t understand something that you feel should be blindingly obvious, that’s an indication that you may have a problem with the book. After all, it’s your job as the author to make that technical detail obvious. So look hard at the reviewer’s comment and see where they’re coming from. Maybe you assumed that the world would interpret some phase or explanation one way, but the reviewer took it another way. Maybe changing one or two words would clear it up; maybe an extra paragraph of introduction; maybe a sidebar. Or maybe the section could be lost altogether or moved later in the book; it’s easy to introduce advanced material too early.
Other reviewers can came across as being incredibly arrogant. They seem to take almost vicious pleasure in finding fault. Their tone suggests that only an idiot could have made this kind of mistake. These reviewers suffer from what experts call penicranial inversion.
This type of reviewer is hard to deal with. You’ll feel defensive—after all, this person is apparently attacking you. Your natural reaction will be to dismiss what they say. But if you look past the aggressive wording, you may well find that the reviewer has a point. You shouldn’t have to take abuse from reviewers, but if you can rise above it, you may find gems buried in the crap.
Other reviewers like to copy edit. They find every little typo, complain about every breach of the punctuation rules, and note bad line breaks and other layout issues. Be careful when reacting to these reviewers. Obviously you can fix spelling issues, but you might want to chat with your publisher about punctuation—every publisher has a house style. And don’t sweat the layout stuff: your publisher should handle it for you (but you might want to double check the final proofs to double check that layout issues reported by reviewers have been fixed).
However, all these strange characters are extremes. You’ll probably find the majority of reviewers are supportive and helpful. Cherish these folks. If you have the opportunity to interact with them, do so. And be sure to thank particularly helpful reviewers somewhere in your book’s front matter.
Handling reviews can be tough. Try to remember as you grind your teeth that it is better to find these issues now, rather than after the ink has dried on the paper.
I’m in London, having just finished presenting at QCon.
One of the tracks was called Reflecting on our Agile Journey - How do we reach Mastery? The more I think about that, the more the title worries me, because it seems to contain an implicit assumption—that mastery is some state that can be reached.
I think there are methodologies which can be mastered, where you can say “now I know it all.” I don’t believe agility is in that camp. For me, agility is all about the journey. Along the way, we’ll always be faced with forks in the road. The agile principles help us decide which to take. And we just carry on, enjoying the trip and doing our best along the way.
This is the fifth 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.
So far we’ve discussed the idea that a book is a narrative, and that the reader is the hero, undertaking a journey to learn new things (to boldly go…). I suggested that you might even want to start your book with an explicit story, something to draw the reader in. So just how do you write in such a way that the reader wants to join you? I don’t pretend to know, but there are some tricks that pragmatic authors use.
First and foremost, always remember that the book is about the reader, not the writer. Your job as author is to help the reader become proficient. You are a mentor, a guide. So always invite the reader along as you explore and explain.
The consistent use of pronouns is a great start. As the author, don’t try to hide behind a passive or stuffy voice. Don’t say “It is widely believed that…”. Don’t say “One could argue that…”. Just come out and say it: “I think that…”. Engage with your reader.
Your reader is a person too, so address them directly. Say things such as “You’ll need to install Xyz now” and “If you run the code now, you’ll see the following output.”.
But remember, you’re sharing a journey. So, whenever possible, try to use “we” and “our” to refer to the reader/author team. Don’t start a chapter with “In this chapter I’ll show you…”. Don’t start with “In this chapter you’ll find out…”. Instead, join the reader as they learn: “In this chapter we’ll see how…”.
Remember what I said about the Dreyfus model in SYWTBAW 3? Novices want to be told what to do. So don’t be afraid to use the imperative voice, particular early on the the book.
Here are a couple of paragraphs from the Rails book.
Back in xxxxx we sketched out the basic content of the products table. Now let’s turn that into reality. We need to create a database table and a Rails model that lets our application use that table.
The migration has a sequence number prefix (001), a name (create_products) and the file extension (.rb, because it’s a Ruby program). Let’s add the code to this file that creates the table in the database. Go to the db/migrate directory and open the file 001_create_products.rb. You’ll see two Ruby methods.
See how the reader and author share the journey: “We need to create”, “Let’s add the code”, and so on. At the same time, the reader is told what to do: “Go to the …” and “open the file”.
Layered on top of all these tricks with pronouns, the book has to be readable and engaging. You need to find a way of injecting energy and passion into your writing. You have to make people want to turn the page, to learn more about your subject. Clearly, technical knowledge helps. A good turn of phrase can make the content more interesting. Light, casual humor (particularly if it is off-beat or subtle) can keep the reader on his or her toes. Adding the occasional piece of trivia or background can add a little spice.
But all of this is predicated on one truth: the voice of a book has to be your voice. It has to be genuine; it has to be you. This is probably the most difficult challenge an author faces on a new book project.
So—how can you find this voice?
My best advice is to look at your book’s content and choose a chapter where you’re really comfortable with the technical material. Then just sit down and start writing. Write without reviewing what you’ve written. Don’t look back and correct stuff. Just write. Keep going for as long as you can. When you stop, save the file without rereading it. The next day, keep on writing. And continue the day after that. At some point, something will click in your head. You’ll find your writing style suddenly gels. Your prose will start to flow and the words will start to hang together well. You’ll know the feeling when it happens.
And when it does, here’s what you do. Save the file you’ve been working on, and promise yourself you won’t look at it again for a long, long time. Instead, choose another chapter and start writing. This time, you’re writing for real. Still keep the flow going, but now it’s OK (actually, it’s vital) to go back and read what you wrote. Ask the readers on your shoulder what they think. Because now you’re writing a book for real.
At some point you’ll have to revisit that original chapter. My advice? Just throw away the one you wrote initially and do it again. It’ll come out infinitely better than it would if you tried to make incremental improvements to your original prose.
When I write a new book, I follow this approach. I plan to throw away something like the first 30 or so pages. And, because I know I’m going to do it, it doesn’t worry me. I no longer have writer’s block. I no longer agonize over the voice in the first paragraph. I just churn it out until I feel comfortable, delete everything I wrote, and then start in for real.
In The Mythical Man Month, Fred Brooks advises project teams to expect to “throw the first one away.” That’s still good advice after 25 years, and it applies just as much to the writing process as it does to software development.
Give yourself time. Give your book a voice.
This is the sixth 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 no particular order:
Work Where it Works
Writing is difficult. Part of the trick of writing is to be able to focus on the writing itself—there’s no point making things harder than they already are. So choose your writing environment carefully, and defend it when necessary.
So just what is a good writing environment? You tell me—everyones’ is different. Some folks I know go down the local coffee shop and blitz out chapters. Other people go to the park. Some write in bed while waiting to go to sleep.
I personally look for an environment where I know I won’t be disturbed. It isn’t good enough that I don’t get disturbed—I have to know that the interruptions aren’t going to happen. Without that, part of my brain is constantly scanning the background, waiting for the e-mail ping or the IM window to pop open. So, when I sit down for a writing session, I kill off all my network applications. I put the phone on DND, and I close the door. The risk of being disturbed drops and my productivity rises.
For this same reason I find I’m really productive is on airplanes: I stick the earphones in and I can churn out page after page.
It really doesn’t matter what environment works for you. Experiment until you find one, and then use it.
Stay Out of Lay Out
Many authors claim that they want to see the final format of the book as they write it. I don’t agree. Remember the underlying axiom: writing is difficult. Why make it doubly so by simultaneously worrying about form and content?
Assuming you’re using a decent tool for creating your book, you’ll be using logical markup. You won’t be saying “set this word in Courier.” Instead, you’ll use markup to say “this word represents a variable name.” If that’s the case layout is simply a matter of associating sectioning and character markup with the appropriate layout elements. You book can change appearance many times without changing anything in the content. With this kind of system, your job is to use the correct markup as you enter content. This lets a designer work on the layout in parallel. It’s just another case of separating concerns to make life easier.
A Time to Write
In some ways, writing a book is like going to the gym. It’s hard work and it feels better when it’s over.
To help us go to the gym, most people have some kind of schedule: they go before work, Mondays, Wednesdays, and Fridays; or they go whenever American Idol is on (the latter folks are fit.) Having a schedule means that you feel an obligation to go. It also means you tend not to schedule other things at the same time, which gives you one less excuse to skip a session.
Do the same with your writing. Pick a schedule for writing and stick to it. Some folks like to set their alarm clocks a couple of hours early and write before the rest of their house gets up. Some folks write after everyone else goes to bed. Or you can write on Sunday afternoons and Wednesday mornings. The key things are to (a) agree a schedule with those around you, (b) make sure it is practical to use your ideal writing environment during those times, and (c) to use those times to get some writing down. An entry in a diary doesn’t get you fitter; time spent exercising does.
End at the Beginning
One of the biggest mistakes new writers make is to start their book by entering “Chapter 1: Introduction” into their editor. No one really knows what their book will contain when they start out, so writing an introduction to it is really pretty futile. Make life easy for yourself and write the introduction last.
So, where should you start? Assuming you’ve already written the throw-away prose while finding your voice, I think you’re best off choosing a chapter where you feel at home with the material. Belt it out, and then move on to something else fairly straightforward. Make sure you have the voice business nailed cold. Show what you’re written to some friends. Get into the swing.
Then change gears. You’ve mastered the writing part. Now look at the content. Is there some area where you don’t feel so confident, or where you need to do some research? Now’s the time to get that out of the way. Tackle the difficult stuff while you’re still relatively fresh. You’ll find it easier to do now than later. And, more importantly, you won’t have it hanging over you while you write. Getting the difficult stuff down also gives others longer to review it.
Cut and Paste is Your Friend
No one gets it totally right when they plan a large project. You always discover things that you thought went here, but that work better over there. So don’t get overly protective of your outline.
As you gain experience with your book, take every opportunity to look at your content and ask whether it is flowing the way you’d like. Cut out text that doesn’t fit. If you know where it belongs, paste it into the new chapter. But don’t try to put it in exactly the right place. Instead, paste it at the very top of the chapter and flag it somehow. Then get on with writing what you were writing originally—don’t break your flow. Then, at some point in the future, you can go back and knit the orphaned piece of text into its new home.
I keep a special dummy chapter available for snippets that don’t seem to have a home. As the book developer, I periodically look to see if any of these snippets might add value to any existing content, moving them into place if they do. I’m not particularly sad if I finish a book and find the bucket still has stuff in it: books are ruined by authors trying to add every single idea they have to the flow.
Interact
Never, ever, write in a vacuum. Show your work to people: friends, colleagues, reviewers. Check with your publisher to see how they want to handle this, but get feedback early, and get it often. If you work with a publisher who offers a beta book program (where books are released as works in progress), see if you can take advantage of it: releasing your book to the general readership early will generate a tremendous amount of feedback.
Save and Archive Often
It’s almost embarrassing to have to say this, but please make sure you back up your book. When the Pragmatic Bookshelf signs a new book, we create a new project for the book’s files in our Subversion version control repository. As the author creates and edits content for the book, we strongly encourage them to commit these changes to the repository, multiple times a day. That way, if they have a hard drive failure they won’t lose their work: it’ll tucked away securely on our servers.
Other publishers may not offer a Subversion repository for your work. If that’s the case, I strongly recommend you set up something similar for yourself. At the very least, get into the habit of archiving your writing onto some external machine or external media on a regular basis. Ideally, keep the content in a version control system.
Use Cross References as Placeholders
Although I’ve written about this before, I’d like to mention it again. Use cross references as placeholders for content you haven’t written yet.
Outline the Plot, not the Paragraphs
It’s just natural: people like lists. And all the conventional wisdom tells writers to produce outlines for their books. So many writers take this to heart, producing long, deeply nested notes that tell them what each paragraph in a chapter should contain.
If this works for you, do it. But don’t feel that strict outlining is necessary. When I write, I start each chapter with a simple list of the things I want the reader to learn by the time they get to the end. I then sort them into an order which seems to make sense as a narrative. Then I replace each item with a section or subsection of prose. I find that this scheme gives me the skeleton I need for a chapter, but it also gives me the flexibilitiy I need when fleshing it out.
This list just scratches the surface—there are whole books on writing tricks. As yo’re starting out, ask your editor for their ideas. Search out more experienced authors and see what they do.
Writing a book is difficult. Don’t make it harder than it has to be.
This is the fourth 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.
Every book has (or at least should have) a voice—a way it speaks to the reader. The voice can be formal, or casual, friendly or aloof, helpful or condescending. One of the main problems facing new authors is finding that voice, and then maintaining it consistently throughout the book. Creating a book’s voice is the subject of this article and the next. In this one we’ll look at how you make sure your book’s content is appropriate for your intended readers. In the next, we’ll look at some tricks for helping a book talk eloquently.
How do you make sure that the stuff you’re writing is right for your readers? Well, think about it in terms of programming. When we write code, we also write tests to validate that the code works. When we write a paragraph, wouldn’t it be nice if we could test it with readers?
Well, most books from good publishers are tested on typical readers before being printed. The process is called reviewing; a manuscript is sent to a panel of both experts and novices for comment.
But that’s a bit like writing all your code before compiling and testing it. If there are problems (and there will be) they’ll be hard to untangle, and the rework will be expensive.
Obviously it’s better to get feedback as you go along. Our beta book process involves a book’s readers as the book is being written. The feedback it generates is amazing (if a bit overwhelming at times). But even this is not ideal—you’re unlikely to release new material more often than once per chapter. The feedback is more timely, but it isn’t real time.
Wouldn’t it be nice if you could have readers with you as you are writing?
With a bit of imagination you can. This is a trick I pass on to all our authors. Most think I’m crazy, but after trying it most report it works well for them.
Do you remember having imaginary friends when you were a child? Well, it’s time to go find them. In fact, it’s time to find three of them.
When writing a book, I suggest you imagine you have three different people looking over your shoulder as you write. Each represents a different typical reader of the book you’re writing:
One imaginary friend is the novice reader. This is the person who knows next to nothing about your subject matter.
The second imaginary friend is a subject matter expert. She’s someone who knows as much as you do—if not more—about your book’s content.
Your third imaginary friend is the picky, average reader. They aren’t a novice, but they don’t really know too much either. What distinguishes them, however, is that they’re that special kind of geek whose pleasure in life comes from finding holes and inconsistencies. (These people are the reason that Texas has a “he needed shooting” defense).
When it comes to inventing these intangible critics, I have one more recommendation. Pick people you know (or that you know about) to act as these friends. Of course, these people won’t really be with you as you type, but knowing who they are makes it easier to imagine their reactions to your creative output. In fact, get pictures of these three people and tape them to your screen so there’s no escape.
Now you’ve invented your own private peanut gallery, it’s time to put them to work.
As you’re typing your book, get into the following habit. Stop at the end of every paragraph and poll your imaginary friends. Ask each in turn a couple of questions: “did that make sense?” and “what questions or comments do you have?”. When you’re starting out, do this for real—ask out loud. I know—it sounds really stupid. But there’s something about vocalizing things that engages a different part of your brain. You’ll find that your three friends actually start to have their own personalities, and they’ll say things to you that you weren’t expecting.
Your novice friend will stop you from rushing through your explanations—you’ll pace things so that they can keep up, and you make sure you concentrate on the essentials and avoid confusing details.
Your expert friend will make sure you stay technically accurate. She’ll also serve a subtle role: when you write a book to be read by a range of readers, it can be a challenge to keep the more advanced ones engaged. But if you imagine an expert reading along as you’re writing, you’ll find it easier to inject little in-jokes and asides that will pass the novice by but that will make the expert feel good about continuing to read.
Finally, the picky friend makes you view what you’ve written critically: he acts as your conscience, keeping you from cheating yourself and your readers as you write.
When you first start out, you have to force yourself to do this. It feels very strange. But by the end of your second chapter, you’ll find that the process has become automatic. You’ll find yourself correcting and improving your writing in real time, as you type.
OK, so this sounds crazy. Surely no one really has these imaginary conversations while they’re writing? Well, I do. And I know other good writers who do. It’s simply a technique for helping you act as your own reviewer—it injects a kind of faux objectivity into what is otherwise a very lonely and subjective process.
And, here’s an interesting twist. Many agile methodologies recommend pair programming as a way of getting two pairs of eyes on each chunk of code as it is written. If you can’t rustle up a person to pair with you, bring your new imaginary friends to your next coding session.
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.
I was talking to the Dallas Ruby group a couple of days ago, and showed them the following code:
class Fred
class << self
def self.say_hello
puts "Hi!"
end
end
end
Someone asked whether it was possible to call the say_hello method. It is. How many ways can you find?
This is the second 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.
There are many classic patterns of storytelling. One of the most enduring, dating back to at least Greek mythology, is the Hero’s Journey. These are tales of epic struggles and courageous resolutions.
Every Hero’s Journey follows the same basic plan. We start by meeting the protagonist, an average person living a standard life. Suddenly, something bad happens to them, normally something unimaginable and outside their control. At this point, our character must make a decision. Do they cave, or do they commit to face the challenge—do the take a risk an embark on the journey?
Once they join the path, they face a series of challenges, often getting harder or more complex as the story progresses. By overcoming each, the hero gradually masters the initial problem.
But the story never ends there. Once the hero conquers all the problems, they face one last challenge. They must return to the real world, which often feels different to them. However, once back home, they get to apply what they learned on their journey. They are stronger.
These stories are so popular because the reader gets to identify with the hero—the reader takes the same journey as the character.
What does this have to do with technical books?
Everything.
Because a good technical book is also a hero’s journey. The reader joins the book already faced with a major challenge—they need to learn some new technique or technology. Thy need to make a commitment to follow the path. Along the way, they need to learn stuff, try things, conquering increasingly difficult concepts and challenges. Eventually they graduate; they’ve learned what they came to learn. But they journey doesn’t end there. Like the hero, they then have to come home, bringing back what they learned.
And good technical authors know this. They don’t structure their books to follow the structure of the framework they’re describing. Instead they structure them to follow the progress they want their readers to take. They make sure the readers know what challenges they are facing, and ensure that the reader is equipped to deal with each. The book builds to a place where the reader understands all they need to know, but it doesn’t stop there. It then brings the reader home, showing them how to bring all his knowledge to bear back in the real world.
A good technical book has a narrative flow. In many of our books, we try to make it explicit, starting the books with a story showing the reader as hero. If we don’t make it explicit, we still try to follow the basic hero’s journey.
Because if you do, you’ll always remember that it’s the reader, not the writer, who’s the hero of the book.
Next we’ll look at the second half of plotting the Hero’s Journey—knowing what challenges to give your readers, and when.
This is the first 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.
I don’t pretend to know too much about writing in general, but I have learned what works for me, and what seems to work for most Pragmatic Bookshelf authors. Don’t take this series as a set of rules—at best treat it as something to think about if you’re considering launching into a book. And I’m sure Andy and our editors will have different (and better) perspectives.
Let’s start at the beginning. With the motivation.
Now that I’m a book publisher (albeit an accidental one), I quite often get folks coming to me saying “I want to write a book.” I typically answer with a single question:
“Why?”
It might appear to be one of those annoying flip responses, but it honestly isn’t. The answer to the question “why?” is the best indicator I know for whether the author will actually end up with a finished book.
Some people treat writing a book as some kind of rite of passage. They say “I’ve always felt I have a book in me, and now’s the time to get it out.” This is the book-as-romantic-journey ideal. These people are unlikely to finish—the bloom will have left the rose well before the third rewrite of chapter six.
Some people answer that they want to write a book to help them with their consulting or training businesses. This answer is almost 180ยบ wrong. Books are not collateral for your business. You are the collateral—people come to the business because of you. If you don’t have the experience that people want, writing a book won’t fix that. The book will follow your reputation, not make it.
Some people have some new framework or library that they want to document in a book. They feel that having printed documentation will add credibility to their project. But that’s not really what books are for. Books certainly can be useful adjuncts to a project, but they really suck as API documentation—by the time the book is in your local bookstore the chances are the project will have moved on and your 1,500 method API listing will be out of date.
So what’s a good answer? I personally look for three things.
Passion. First and foremost, an author needs to be passionate about the subject. They’ll love it, warts and all. They’ll live it—it will take up their free time. They’ll be wired into the community—they’ll be known by the readers of mailing lists. They may well have a blog where they talk about their interest.
Evangelism. Just being passionate is not enough. Good authors also have a mission: they want the rest of the world to share their joy. They want to spread the knowledge to as many as people as possible, using as many channels as possible. It’s not that they want to tell people what to think or what technology to use. No, they have this zeal because their subject makes them happy, and they want to share this joy with others. They honesty feel the world will be a better place once their book is written.
Practical knowledge. Good books are not written from an ivory tower. You can’t just read the existing FAQs and online documentation, then write a world-class book about some topic. You have to have used it, and used it a lot. You need to know the good and the bad\; the areas where it helps, and the areas to avoid. Why? Because that’s your value to your readers. Remember, your passion is to help people do something better. Unless you have practical experience, you’re unlikely to be able to do that—readers will soon realize that you aren’t authoritative.
OK, so I’ve spilled the beans. Does this now mean that the Pragmatic Bookshelf will get inundated with proposals written to push my hot buttons? I hope not, because prospective authors who do that are really just fooling themselves. They may get a book accepted, but our experience over the last 4 years is that they probably won’t finish their book project.
But, if you have the passion, and you feel driven to share your experience with others, there’s little more satisfying than seeing a your ideas on the shelves of your favorite bookstore.
In the next two posts, we’ll look at the Hero’s Journey, the basis of most good technical books.
Bob Payne attended The Rails Edge in Reston, where he set up a mini studio and interviewed all the speakers. He posted my interview today. We discuss the dangers of monocultures, Erlang, education, life, the universe,…
And, if you’re wondering about Erlang, look for an announcement from the Bookshelf next week. (Or, if you’re feeling like a bit of sleuthing on our site, the code “jaerlang” might help…)
