#2782

Writing A Programming Book

Really you should do yourself a huge favor. The next time one of your friends suggests you write a book, just ignore them. That’ll also save you the onerous task of reading the rest of this post.

Still reading? Oh dear. Well I guess I feel compelled to inflict some well meant advice. This is based on collaborating on three books in the last few years. I’ve also written numerous technical papers, a PhD thesis (i.e. another book) and several published articles. Glutton for punishment, that’s me.

1) Understand what you’re writing about

If you’re contemplating writing a technical book on something, then you probably already consider yourself to be something of an expert. Writing a book is a great opportunity to round out all the dark corners of the topic and understand it completely. There’s a lot to be said for learning something by forcing yourself to explain it to someone else. This is not an invitation to decide to write a book something as you’re learning it. The result will read like a Presidential candidates manifesto but with fewer outright lies.

Even if you know the subject cold that doesn’t mean you understand what explaining it to others is going to entail. When you assemble the outline (see #3) do it with an eye to identifying topics that will be harder to explain or less familiar to your audience (see #2).

2) Understand your audience

Who is the book for? What parts of the technology are they familiar with and what will be completely new to them? This will help identify additional material you may have to add when it comes to writing the outline. Creating a persona to describe your reader may be helpful.

For example when we wrote the C++ AMP book we decided that our readers would have a reasonable amount of C++ and STL experience but might not be familiar with the new features in C++11 so we included some additional material on lambdas and references to additional reading material for readers who needed it.

3) Have an outline

A book outline lays out each chapter of the book, the topics covered in each chapter, any accompanying material like sample code, and the approximate page counts. This will help you estimate the size of the Herculean task ahead of you and at some point will boost your spirits when you realize that you might be halfway done and the end to the use of senseless split infinitives may be in sight.

Of course only an idiot would write a book without a complete outline. Believe it or not we didn’t do a very though job on the C++ AMP book outline. The original was missing several chapters we had to write for the final book. This was, erm, well shall we say, painful.

4) Write the samples first

In many ways a technical book is really an explanation of the samples. In particular programming books have samples or case studies associated with them. If the code is hard to understand the book will still have to explain it. The better to code the less time you will spend doing additional writing.

Expect to write the samples before the chapter they are described in and then to rewrite the samples as you write the text to make them seem like they go together. For example you may find that and explanation is better served using a specific terminology like master/servant. Don’t hesitate to change the code to use the same terminology in method and variable names. There’ll be another blog post on writing good sample code for books, which turns out to be a bit different from writing good production code. That way we can all bicker about bracket placement later.

Make the samples open source and distribute them for review with the draft chapters and ask for reviewer feedback. When I wrote the samples for parallel programming with Visual C++ I hadn’t written any C++ in a long time. I was lucky enough to have members of  the PPL, STL and MFC teams take a look at my code before we shipped. It was better as a result and I learned a thing or two along the way.

5) Review work in progress

Even fiction authors have people who read early drafts of their work. For technical writing this is absolute must. Ideally you should have reviewers who represent your audience and can give you feedback on the overall readability of the book. You should also have subject matter experts who can ensure that the content is completely correct. You can also put draft chapters up on the web and allow anyone to send you feedback. Some publishers offer draft books for review and ask people to pay for them. Personally I’m not a fan of this as it limits the potential readership and thus feedback. Not to mention paying for a “beta” doesn’t cut it in the rest of the software world.

Sign up more reviewers than you think you need. Reading a book is a big time commitment and people often don’t manage to provide feedback on all the content. Remember all they get is an acknowledgement (see #9).

6) Review feedback is just feedback

If you’ve gotten a lot of review feedback (see #5) then you have to decide what to do with it. Sometimes different reviewers will provide conflicting feedback. Reviewers have many different motivations and perspectives. Some reviewers may be more or less like your intended audience. Some may be keen that you show everything in the best possible light, others may be far more critical.

All feedback should be addressed but this means you should take it into consideration and reword or rewrite accordingly. Don’t feel like you have to take a reviewer’s suggestions verbatim, especially if you don’t think it will help your audience. I can think of several cases where I outright did not include feedback because I didn’t think it served the reader and others where I completely rewrote sections of the book based on feedback from the same person.

A great way to see this process in action is at a patterns writing workshop. It’s amazing to have readers explain their interpretation of your writing to you in person. Ralph Johnston’s students at the University of Illinois provided a lot of feedback like this and it proved really helpful for our C# book.

7) Make sure you have a good editorial team

Good editors are like good testers. We all think we can ship without them, the first time. if you try a second time you were either lucky of not that smart. Good editorial and copy editing can really make your book. An editor can really improve the overall structure of your book and flush out inconsistencies. A good copy editor will make your book far more pleasant to read. Conversely, a poor editing team may actually do more harm than good, even introducing errors in technical content.

Make sure you’re clear with you editorial team as to how you think things should be laid out, especially when it comes to technical terms. I spent many hours italicizing array when it referred to a C++ AMP array<T> type and un-italicizing it when it simply referred to a sequence of values. This is not a fun way to spend a sunny Sunday afternoon.

8) Understand your production schedule

Books are somewhat odd things. The writing doesn’t have many hard deadlines, except for the ones you set yourself, and the effect of being late with one chapter has a linear ripple effect through the rest of the schedule. The same is not true of production.

Many publishers use contractors for editing, indexing and layout or have staff booked to work on your book for a set time period. If you blow a deadline for production by a day it might cost you a couple of weeks as the people you are relying on for the next production step are now unavailable. Most of these steps are also very linear. If layout is late then indexing cannot start (it requires final page numbers) and you may loose that person’s time too. A slip on your part of a day or two might delay the book by several weeks or a month.

In short you want to really understand the production schedule and make sure you hit it. Ideally the production team should be continually reminding you about this and making sure you’re clear on the deadlines and what it means to miss them. This really helps when all you can think about is how to explain some really tricky concept in Appendix A. Good production people will keep you on track, bad ones will mention in passing on a Wednesday that they need a piece of writing or review on Friday or the schedule is out the window.

9) Acknowledge your team

One of the most important sections of any technical book is the Acknowledgements section. Writing this sort of book is definitely a big collaborative effort but all the reviewers, editors, artists and others don’t get their name on the cover. Just because this appears at #8 doesn’t mean it’s the last on the list. I often start the acknowledgements really early on in writing just to make sure nobody gets left out.

I’ve been very lucky to collaborate with several Microsoft product teams as well as reviewers from The University of Illinois, Intel and Microsoft Research as well as many individual reviewers. You’ll find them acknowledged in each book.

10) Don’t have any other hobbies (or friends)

Writing a book is a lot of work. I lost count of the number of nights and weekends I worked on either the text or the sample code. I spent many a Saturday afternoon with nobody but my co-author to talk to on IM. Remember, writing a technical book isn’t going to make you rich. Don’t blow what little money you do make on a divorce attorney.

You reached the end

Then maybe you should think about writing a book! Now I’ve recovered I’d write another one, my significant other might have things to say about that. Seeing your book in print is a really good feeling and meeting people who’ve read it and got something out of it is even better.

Well that’s about it. Many thanks (yet again) to Colin, Roberta, Nelly, RoAnn, Kate, Judith, Stephen, Ralph all of whom taught me valuable lessons along the way.

There are links on the right hand side of this page to the various books I’m talking about here. You can also look at the code on CodePlex and read both the patterns & practices books free on MSDN (C++ and .NET)