FROM THE ARCHIVES OF PRAGPUB MAGAZINE, NOVEMBER 2018
Planning Your Tech Book: The Value of Brain Dumps and Outlines
by Brian MacDonald
📚 Connect with us. Want to hear what’s new at The Pragmatic Bookshelf? Sign up for our newsletter. You’ll be the first to know about author speaking engagements, books in beta, new books in print, and promo codes that give you discounts of up to 40 percent.
You’ve got a great book idea? Congratulations! The idea is where you start in writing a book. And the next step is writing, right? Not so fast. There are a few crucial steps in developing that idea into the germ of a publishable book.
If you’re thinking of writing a technical book, you probably have an idea of what you want to write about. Right now, that idea is probably a thing: some language, some tool, some framework, some management technique. That’s a pretty commonplace to start, but it’s not enough for a book, not in the current publishing environment. If you start by thinking “I want to write about CoolFramework.js,” then you’ll probably start by listing features or components, and explaining how to use each feature in turn until you run out of them. That’s useful information, but it’s documentation, not a tech book. Documentation serves a purpose, but it’s a fundamental part of the product itself, not an extra you need to pay for. Documentation is usually available on the Internet for free, and that’s not the right model for a tech book.
Define the Problem
Instead of focusing on a noun, focus your idea on a verb. Specifically, ask yourself what problem this technology is supposed to solve. What sorts of things is the user going to write with this language? What issue does the tool fix? What is the reader going to DO after they’ve read your book? You’ll probably find yourself answering with a full sentence, and that’s where you’ll find the verb. You want the reader to do, to make, to code, to design, to solve. Beware of verbs like “understand” and “know.” They’re great verbs for their own purposes, but more suited to academic books than the practical guides publishers are looking for currently.
Define the Audience
Once you know what your reader is going to do, think about who that reader is, because that’s going to dictate a lot of the writing choices you make. Many authors try to define as broad an audience as possible, in the hopes of maximizing potential buyers. But when you try to write for everybody, you make it much harder on yourself, and you end up alienating your actual audience. Think instead about the most natural audience for your topic. If you’re writing about a JavaScript framework, your audience is probably front-end developers, which is a pretty broad group on its own. If you’re writing about data science with Python, your audience is data scientists, which seems like you’ve narrowed it down, but it’s still a fairly large group.
Ask yourself who has the problem you’re trying to solve: Enterprise developers? Mobile developers? Hobbyists? Students? Once you’ve identified the group, think about the background that your audience will have. I find it helpful to think about a single example reader at this point (what technical writers call a “persona”). How technical is she? Does she have programming experience? If so, in what languages? If you’re writing about a JavaScript framework, you can probably assume the reader has some understanding of HTML and CSS. If you’re writing an introduction to a functional language, you might assume your reader has a background in procedural programming, or maybe no programming background at all. The choice you make will dictate the scope of the project later on.
Define the Approach
There are two basic approaches you can take to technical content: reference and tutorial. Reference content is the stuff you find in most documentation: it defines features, describes syntax, lists options. The goal of reference content is to be comprehensive. Reference content isn’t meant to be read from start to finish. The reader drops in, finds the answer he needs quickly, and gets out. A dictionary is the purest form of a reference. As I mentioned earlier, reference content is often found online, and is usually free. As a result, readers usually aren’t willing to pay for references anymore, and publishers aren’t interested in them.
A tutorial, however, has the form of a story. Readers have a starting point, the author takes them through a series of steps, gaining skills along the way, and they emerge at the end having achieved their goal — they can now solve the problem that you defined at the beginning. Good tutorial content is harder to write than a reference, which makes it harder to find online for free. Readers are willing to pay for the experience of a tutorial, which is why publishers are most interested in them now. If you defined the problem with a verb a couple of steps back, you’ve taken the first step toward creating tutorial content.
Define the Scope
By this point, you have a pretty good idea of what you want to write about, and for whom. But there’s still a matter of “how much.” The most common mistake writers make at this point is to overestimate the amount of background needed. If you’re writing for web developers, do you need to explain the origins of the web, how HTTP works, and the principles of web design? Probably not. If you’ve defined your audience correctly, trust them to know the things you assume they already know. On the other end, think about how far you plan to go with a topic. If you’re writing about chatbots, you’re probably going to scratch the surface of AI and machine learning, but you don’t need to go into the advanced mathematics and heuristics needed to create an AI like IBM’s Watson. Defining the scope properly will give you an idea of how long the book is going to be, both in terms of page count and the time it will take you to write, so it’s good to nail that down early.
Check Out What’s Out There
Now that you’ve refined your idea with some specifics, it’s time to do a little homework. You don’t want to put months of time and effort into writing a book only to find out that someone has written it before you. Fortunately, Amazon is an effective research tool for publishing. Type in some keywords that describe your topic and see what comes back. There might be a lot of books on your chosen topic, in which case, you’ll have to look at each one more closely. What do they cover? Who’s their audience? Are they out of date? Your goal is to find something to differentiate your book from ones that already exist. You might need to back up a few steps and define a different audience, or take a different angle on the problem. In the worst case, maybe the exact book you want to write already exists, in which case you’ll have to decide whether you want to continue.
On the other hand, maybe there aren’t any books on your chosen topic, in which case you’ll have to ask yourself why that is. If you’re lucky, it’s because the technology is new, and nobody has a book out yet. Or it could be that the audience for the book is too small to interest a publisher. Sometimes enthusiasts get stuck in an echo chamber, where it seems like everyone they know is using the same language or framework, but it doesn’t have any traction in the wider world. With new technologies, it can be hard to tell which situation you’re in. You need to take an objective look at your topic, and maybe do some research into user numbers to determine if you have enough of an audience to write for. This isn’t wasted effort, as you’ll need those numbers to convince a publisher later on.
Make an Outline
Yes, I said make an outline. If that’s causing you flashbacks to high-school English classes, there’s a reason. While you’ve done a lot of the groundwork already, the only way to really know what the content will look like is to start writing stuff down. An outline provides a shape to the book, a framework to hang content on later. You’re not locking yourself in at this point; outlines can change throughout the writing process. To take the pain out of outlining, I recommend a two-step process: brain-dump, then refine.
Brain-Dump First
At the beginning of this process, you defined the problem in terms of a verb. Now take it a step further and start thinking about tasks. What are the things that readers will do with this language, framework, or tool? If you’re an expert in it, think about the things that you generally use it for. If you use it at work, walk through a typical day. If it’s a side-project, walk through a typical session. Write those things down. Don’t worry about whether they’re obvious tasks or edge cases, and don’t try to put them in order; just get them down somewhere.
Keep your focus on verbs rather than nouns. It’s easy to start thinking about features — if you’re writing about a language, you might start thinking about data types, functions, interfaces, concurrency, and other nouns. That way lies documentation. Instead, think about what the reader will have to do with those features. You can find outlining or planning apps out there to help if you like, but I normally just use a plain text file or a piece of paper. This brainstorming will probably take multiple sessions over a period of time. You might think of something while brushing your teeth or doing something else completely unrelated to your topic. That’s normal; just write it down when you get a chance. Eventually you’ll run out of ideas, and now it’s time for the next step.
Refine the Outline
Take the pile of tasks you’ve created, and start to sort them into some kind of order. Take the low-hanging fruit first, and put it up front. Then take the edge cases, the stuff you’d only do rarely, and put those at the end. Maybe some of them are too much edge-case to include, but don’t throw them away yet. If there’s something you don’t think you should include, set it off to the side; you might change your mind later. That will leave you with some tasks that fall in the middle. Start looking for patterns, a logical progression from one task to another. Maybe “make a login widget” is one task. That might lead to “verify a username and password,” which might in turn lead to “access the user database.” That tells you what order those things need to go in.
Once you’ve done that much sorting, you’ll probably be left with things that don’t have an obvious home. Which is more important, search algorithms or JSON encoding? You don’t have to have it perfect right now. If there’s no obvious progression or hierarchy to the topics, just stick them in a reasonable place and move on. When you get to the writing phase, you’ll have more information to make your choice.
You’ve done a lot of work at this point. You’ve taken a vague idea and refined it into something that you could pitch to a publisher. You even have the framework to start writing. I don’t recommend getting heavily into the writing if you plan to work with a traditional publisher.
About the Author
Brian MacDonald has been an editor of technical publications for over 18 years. For most of that time, he ran his own business, with clients including O’Reilly, Wiley, Apress, Wrox, Osborne, and Manning. He also spent a few years as a technical writer at Microsoft. He has co-authored two editions of Learning C# and Learning ASP.NET for O’Reilly. He lives in southeastern Pennsylvania with his wife and son. You can follow him on Twitter at @bmac_editor.
Brian was the Senior Acquisitions Editor for the Pragmatic Bookshelf when he wrote this piece.
