Title: Writing a Technical Book

Author: Martin Moene

Date: 06 May 2015 16:49:59 +01:00 or Wed, 06 May 2015 16:49:59 +01:00

Summary: Adam Tornhill discusses motivation, publishing and how to stay focused without ruining your life.

Body: 

Do you dream of writing your own technical book? I hope you do – our programming profession needs more high-quality books. In our fast evolving field there’s an endless amount of new topics to cover and timeless ideas to rediscover. This article is here to help you get started. I’ll make sure to give you a high-level overview on everything from the initial planning to tips on different publishing models. You’ll also learn about the motivational hacks I used to stay on track and make a steady progress on my own books.

Why care?

Well, there are certainly people with deeper insights than me. But what I can share is advice from a perspective that might be close to where you are. I’m not a professional author in the sense that I make a living from it. Instead I balance a full-time job, a family and something resembling a social life with my writing activities. That means I had to learn to use my time efficiently.

My writing career has also been non-traditional in the sense that I started-out with self-publishing. I wrote two books on my own before I decided to get a publisher. That means I can compare these competing models. As you’ll see, there isn’t a clear-cut between them; Both models have their advantages and drawbacks. I tell you more about it soon. I’ll also share my experience of working with a publisher, what they can do for you and what you can expect when it comes to royalties.

All my advice is subjective. This is what worked for me. I view this article as the kind of guide I’d like to send back in time to my younger self to save both time and effort. Since I cannot do that (yet), I decided to share it with you. I hope you’ll find it just as useful as my younger self would.

Start small

How often have you heard that writing a book is hard work? A work that will consume all your waking time, ruin your social life and leave you with less monetary return than what you’d earn from refunding deposit bottles. I won’t dispute it – there's a lot of truth to it. That’s why you need to approach your book like you would take on any other large project that affects your life.

Returning these bottles (Figure 1) earns me more money than an hour of writing does.

Figure 1

While I wanted to write a book for a long time, that’s not how I started. Instead I tried to build my experience and develop my writing style in smaller steps. The first pieces I wrote were articles. At that time, back in 2004, I’d come back to code in C after some intense years in object-oriented land. That perspective made me approach the code in a different way. More specifically, I realized that some principles I’ve learned could benefit C programmers as well. I decided to do a write-up of my experience.

These articles grew into a series I called ‘Patterns in C’ [1]. I published it on my blog [2] and in C Vu. By starting small I got to develop my own voice. In fact, as I re-read the articles now, I note the gradual change in style over the course of the series.

I recommend a similar approach: get started by writing smaller pieces on a regular basis. You’ll find that you learn a lot that translates to larger writing projects. It’s also a way to save time once you embark on your full book. Writing is just like any other activity: the more you practice, the more fluent and easy it comes. This is particularly important if you, like me, aren’t a native English speaker (I grew up bilingual with Swedish and Czech and had to practice a lot to get a decent command of the English language).

You’ll notice that all the practice you put in lets you write faster. That’s a good thing since it allows you to spend more time on background research, structure and re-drafting your writing. Remember, what makes good writing is constant re-writing. Often, writing the initial version of a chapter or article takes-up less than half of the total time spent on it. Practice gives you the margin you need.

Expand your horizon

Once you’ve created a collection of blog posts or articles you might want to take the next step. You’re fortunate; today, it’s easier than ever to grow your collection into a book.

My first book was more or less an experiment to gain experience with a larger format. I had read about Leanpub, the new self-publisher start-up, and wanted to give it a try. I decided to package my article series on ‘Patterns in C’ [1] into a book. I’m glad I did since it taught me a lot. It’s also a motivational boost once the first royalties from your own writings start to come in. It probably won’t be much money, but trust me on this one; You can’t put a price on motivation. The knowledge that someone pays real money to read your work will help you keep going.

I’ll discuss self-publishing in a minute. But first, let’s consider the reasons why you should write a book.

Money and motivation

Ever heard that 95 percent of all programmers never read a technical book? Unfortunately that’s a pretty precise estimate (perhaps the only precise one within software). For you, as an aspiring author, it means your potential market is limited from the start. Technical books just don’t sell well. And the rare exceptions, classics like Design Patterns or Refactoring, are just that: exceptions. We’ll have a discussion about royalties soon, but my advice is that money shouldn’t be your primary motivation. Fortunately there are many other rewards for you.

One of the biggest wins of writing comes when you view it as part of a learning process. When you try to explain a concept to someone else, something amazing happens. The process of explaining gives you a new perspective. You’ll find that you learn just as much about the subject as your readers do. The knowledge you gain is the most valuable part. It will transfer to your day job and make you a better programmer.

Another big reward is the feeling of achievement. Through your writing you’re able to affect people and change the course of their technical lives. Over the years I’ve received emails from readers all over the world. There’s something deeply fascinating about that and it gives you something that’s worth more than the next royalty cheque.

Finally, there’s the very act of creating something. If you look into motivational psychology you’ll find that what makes us happy isn’t necessarily fame or commercial success. Happiness is grown when you work towards challenging, yet achievable, goals. Writing about a complex topic like programming will put you right in that spot.

Let me share a story. My second book, Lisp for the Web [3], wasn’t something I planned. Years earlier I had published an article with the same name. Around that time the Lisp language experienced a small Renaissance. Paul Graham had written about how Lisp allowed his start-up to develop at a higher pace and outperform their competitors when developing a web application.

So Lisp was cool again. But there was virtually no material available on how you actually approach web development in Lisp. I decided to find out and share what I learned.

The ‘Lisp for the Web’ [3] article was as close to a hit as I probably ever get. My mailbox flooded with comments and nice feedback. If I was smart I should have evolved it into a book right away. Since I wasn’t, I just let the article stick on my homepage and get outdated. Never let an opportunity slip like that, please.

Six years later I started to feel sad about the state of my article. The libraries I used for the code had evolved, some of the open-source packages were abandoned and my sample application didn’t even work anymore. I didn’t want people interested in Common Lisp to come to my article, become frustrated when it didn’t work and were thereby discouraged from learning Lisp. I decided to give the article a face lift and get rid of the bit rot in the process.

Since I was already familiar with Leanpub I evolved the article into a short book. A model like Leanpub fits this material well. Because they only do e-books, it’s easy to keep the material up to date as the technologies advance. Another advantage is that self-publishing allows you to control the price. Let’s see what that means to you.

Experiment with your book price

Most self-publishing services let you specify the sales price yourself. How much of that do you get? Well, that varies a lot. At Leanpub you get a royalty rate of 90 percent. As you’ll see when we discuss publishers, 90 percent is an astronomical rate. Compare this to Amazon where you get either 35 or 70 percent. Of course, the royalty rate alone isn’t the whole story. Amazon probably lets you reach more people. The good thing is that you don’t have to choose as long as you retain the copyright yourself.

So what’s an appropriate price for a book? It depends on your goals. With Lisp for the Web [3] my main motivation was to give something back to the community. Since I wrote the book to be read, I used the option to make it available for free. I also specified a suggested price of 4.99$. To date, more than 1300 people have downloaded Lisp for the Web. Of those, approximately 20 percent chose to pay for it. A pleasant surprise is that some readers pay more than the suggested price. Programmers are good people.

Making your book available for free could be a good business model. It helps you build a personal brand and may help you boost your main business. If you’re a consultant or want to use the book to build buzz around a certain product you’ve invested in, the free as in beer model may be just right.

Of course, free books is just one possible segment. You’ve invested a ton of time and expertise in your book. Charging 10–20$ for all that is still a bargain to any reader. When we buy a technical book, our primary investment isn’t the money we pay for it but the time we spend reading it. So my advice is to look at the price of similar books and charge at least the same amount yourself; If someone’s interested in your book, a few dollars extra won’t stop them from buying it.

Decide your publishing model

So far I’ve only talked about self-publishing. While I like that model, a good publishing company has a lot to offer. It’s also a radically different way to work that will affect your writing experience.

After self-publishing two books I got a contract with the The Pragmatic Bookshelf [4] for my new book, Your Code as a Crime Scene [5]. My experience has been almost exclusively good and, thanks to the Pragmatics, I managed to write a much better book than I could have done on my own. You see, a good publisher will do a lot for you:

• Contract equals motivation: Your book is only in an early stage, yet someone already believes in it and is prepared to invest time and real money in making your vision come true. Getting a publisher is a motivational boost that helps you get started.
• You get a project editor: Your editor is a skilled author that will coach you, provide continuous feedback and review your material as you write. You’ll spend a lot of time with your editor so make sure it feels right from the very start.
• Focus the message: Let’s admit it – we programmers love to add cool stuff to our creations. Writing a book is no different. You’ll probably find that you try to cover too much ground. A good publisher helps you focus on the topics that really matter to your readers.
• A step up in quality: Publishers do a lot of hard work for you. They provide a copy editor, design your cover and make sure to index your book. If you self-publish, you want to hire someone to do that for you. It makes a marked difference.
• Gain status: While anyone can self-publish a book, getting your work out under the brand of a respected publishing house means something in our industry. It gives you credibility and makes people pay attention to your work.

With the benefit of hindsight, would I go down the publishing route again? Yes, definitely. The Pragmatics are amazing and I’m happy that I worked with them. I learned a lot and I’d definitely recommend them to you. When I write my next book, I’ll consider the Pragmatics again.

That said, you may well find that self-publishing fits you better. Self-publishing has some real benefits:

• You’re in control: When you self-publish you can be as provocative as you want, you get to use your own style and have full control over every word, image and marketing step. After all, it’s your vision and here you own it.
• The topic is yours: Perhaps you like to explore non-mainstream techniques and esoteric programming languages? That’s all good and it’s an important way to grow as a developer. However, the market for embedded Idris programming or recursive decent parsers in colorForth is unfortunately quite limited. As a consequence, you may be unlikely to interest a publisher in the stuff you want to write about. Self-publishing lets you ignore the market and write the kind of book you care about. Remember, the main value of writing a book is the learning experience you’ll go through.
• Write in an agile way: An interesting trend is that several authors now release their work in a very early stage. Some books meet their audience with little more than a planned table of contents. This lets you publish your work early, get feedback and improve as you go along.
• Retain the copyright: Since you own your own work, you’re free to re-package it and publish it any way you want. Perhaps you want to re-work parts of it into another book? Or you want to publish individual chapters as articles on your blog? That’s fine – you own it.

From my experience, giving up full control over my work was the hardest step. A good publisher, like the Pragmatics, will of course still listen to you. But you will have to give up on some of your own ideas. When you self-publish, you own every step of the process. That’s important to remember as you chose your publishing model.

Find a publisher

While my personal experience with a publisher has been great, everyone hasn’t had the same fortune. Publishers differ a lot. You can see that in the books you buy yourself. Some publishers serve as a quality mark while others vary much more in what they allow to pass through.

You can build on that when searching for a publisher. Consider your favorite technical books – who published them? Since you want nothing but the best for your own book, that’s the route you want to take. Sure, you as the author are the most important ingredient to your book, but a publisher will affect your work at a profound level. Make sure you know why you choose the publisher you do.

Once you’ve narrowed the field of potential publishers you need to consider what they offer you. Will they do both print and e-books? What distribution channels do they use? How can they help market your book? And what about the royalty rate?

When I started to consider a publisher I had narrowed my choice to four different companies. At the end I only contacted The Pragmatic Bookshelf since they were the only publisher that offered a royalty rate that felt fair. At the Pragmatics you get 50 percent of the gross profits on your book. Other publishers typically offer a royalty rate of 7-15 percent, perhaps with a possible advance pay.

Of course, the royalty rate is just one factor to consider; Remember, you’re unlikely to make much financially from the sales alone. Most of the money you make will come from indirect sources like your stronger personal brand, related training courses or increased salary since you’re now a published author.

Get a contract

Once you’ve decided upon a publisher you need to put together a proposal for your book. The publisher typically specifies what your proposal should include. In general, they want the following:

• Your idea: Provide a short overview of the topic you plan and how you want to approach it. Draft a table of contents with all key chapters. You’ll probably change it later, but this helps making your idea more concrete to the people that will review it.
• A writing sample: To write a book you need to show your publisher that you can, well, write. Make sure to polish your sample. Once you have a draft, put it away for some days before you re-visit it. That simple trick gives you a more unbiased view of your writing and you’re likely to discover gaps and improvements that you had overlooked the first time.
• Motivate the book: You need to tell them why your book is a good idea. Speculate a bit about the potential market and make sure to communicate why you’re the best possible author to capture this idea.

Your Code as a Crime Scene wasn’t my first proposal to the Pragmatics. Actually, I’d sent them Lisp for the Web and offered to do an extended version of that book. Now, something unexpected happened. The publisher replied that they weren’t interested in my Lisp book but that they liked the writing style. They also showed that they cared by doing some quick research on me. That’s where they found my online plans for this strange code as a crime scene stuff. So, the publisher asked if I wanted to propose that book instead. I did and got my contract.

The moral of this story is that even if you get a rejection, good things may happen. Don’t give up. Consider it a starting point instead. Re-shape your book, take a different angle and try again. The publishers need you so they’re happy to get proposals. Remember, you as a potential author is the one that’s adding the most value. Without authors there wouldn’t be anything to publish.

Master the writing process

Writing is a skill like so much else. There are several good books that help you improve as a writer. My personal favorites are The Elements of Style (Strunk & White) and Keys to Great Writing (Wilbers). I can’t compete with those, so let’s look at the surrounding activities instead.

Chose your tools wisely

Writing a book is quite similar to programming. In fact, I recommend the same tools. Write in a pure text format, for example markdown, and use a text editor that supports your format.

You’ll find that you spend a lot of time re-writing. In order to do that efficiently you want to put your book under version-control. If you stick to my advice and use a simple text format for markup, you’ll be able to compare revisions and rollback edits that didn’t work well.

Whatever you chose, don’t make the same mistake as I did initially and think that a word processor like Word or OpenOffice is good for, well, word processing. They’re not. Today’s books are delivered in a variety of formats like MOBI, EPUB, HTML and the humble dead tree. Converting from a Word document to one of those formats is just painful. Don’t go there.

Plan your book

Start with a detailed outline of your book. I can’t stress the importance of this enough. In the past, I used to skip this step and every time I did it came back to bite me. The result is a trail of abandoned book projects. You don’t want that.

When I say ‘detailed outline’ I mean it. Write a short overview of each chapter and capture its key points and take-aways. This step helps you fit the individual pieces into a coherent whole.

You’ll probably find that some chapters don’t quite fit the overall structure and tone of the book. In that case, just drop them and keep the material for other purposes. You also have to be prepared to change course and narrow the scope. Since you have it all in version-control, you can always go back if you need to.

It’s during this planning stage that writing departs from programming; Writing a book is more predictable. There are less things to discover. As such, the more time you spend up front, the easier the rest of your writing. I promise, you’ll still have plenty of opportunities to develop ideas that pop-up and the new connections you make as you progress.

Stay on track

Remember, writing a book is time consuming. I often got the advice to reserve dedicated writing time. Sure, it’s possible to spare a day or two but it’s not enough to make any real progress. If too much time passes between your writing sessions you’ll lose good ideas, have a harder time maintaining flow once you write and, worse, it gets easier to just drift away; Before you realize it, a whole month has passed without a written word. That’s how book projects get abandoned.

So do reserve the days you can. Do invest some of your holiday to move your book forward. But you need more. I recommend a complementary approach that lets you make progress on your book while at the same time balancing work and other obligations.

The way I do it is to print a calendar and nail it to the wall as you see in the picture below. Every day that I write at least 30 minutes on the book I’m allowed to cross out that day in the calendar. The goal is to build the longest, unbroken chain of productive days. (Figure 2)

Figure 2

The key here is to set a realistic goal. I often wrote several hours a day, but my goal was a modest 30 minutes. That’s really nothing and it’s always do-able. I wrote in airports, on trains and in cars (you see – if you ever needed an argument for self-driving cars – here you go). I wrote on my birthday, I wrote with fever after catching the ’flu. I even wrote on the day our cellar got flooded in the worst rain of the past 150 years. After pumping out water and losing a fight to mother nature I was exhausted. But still – 30 minutes? I can do that.

When you write every day you stay on track. You make progress and keep your ideas alive in your head. Before you know it you’ve completed one more chapter and moved closer to your goal.

Reflect your learning

Once you have finished your book you’ll look differently upon your material. Remember, writing is a learning experience and you have a much deeper understanding of your topic afterwards. You want to reflect that learning in the early chapters you wrote. That’s why it is important to go back and improve your material.

Of the whole writing process, this is the hardest step. Not from a technical point of view but from a motivational. You’re done and you’re probably mentally exhausted from the whole project. Yet you’ll find that now is the opportunity to take your book to the next level. To move beyond good enough to just great.

Market and promote your work

If you have a publisher they’ll help you market your work. But even in that case much of the responsibility is yours.

There are several things you can do to spread the word about your work. Give away free copies, lots of them. Provide free material on the book’s homepage. Talk at conferences and publish articles that cover some of the highlights of your book. Record podcasts and make short videos to demonstrate some core ideas.

The whole point is to get people to talk about what you have done. Since I personally love to speak at developer conferences and share what I’ve learned, that’s what I focus on. That may not be for everyone. But whatever you chose, make sure you enjoy it.

Let’s get started

We’re through our quick tour of the book writing landscape now. Since you've made it this far, I conclude that you’re serious about your book project. That’s great! It’s well-worth the effort as long as you manage to find a sustainable pace. Remember, the book’s going to consume much of your time. It’s going to be hard and frustrating. It’s also one of the most rewarding things you can do as a programmer.

References

[1] https://leanpub.com/patternsinc

[2] http://www.adamtornhill.com/articles.htm

[3] https://leanpub.com/lispweb

[4] https://pragprog.com/

[5] https://pragprog.com/book/atcrime/your-code-as-a-crime-scene

Notes: 

More fields may be available via dynamicdata ..