How to Write a Technical Book
|Home | Articles | Books | IT Surveys | Podcasts | Contact Us | Announcements | Site Map|
The goal of this page is to share my hard-won experiences writing books. The bad news is that writing a book is hard work and frankly it can be very difficult to break into the publishing industry. The good news is that writing a book can be personally and professionally rewarding. Think long and hard about these observations.
Rethink your idea
Finding a publisher
The writing process
The book is published
Writing a book is really, really, really hard. It sounds like a great idea at first, something you may have dreamed about for years, but it's a heck of a lot of work in practice. Your book will consume all of your precious free time for months, if not years. It will strain your relationships with other people, it may even effect your health. I'm serious. I highly recommend that you talk with other people who have written books before, try to talk with someone who wrote several books as well as someone who has written only one, and ask them about this. The best time to back out of writing a book is before you've even started.
The easiest way to get published is to already have been published, a typical Catch-22 situation. I first started writing when I was in University: I turned one of my papers into a five article series which I sold to a local computer paper. They liked the series so much that they picked me up as a columnist. A few years later I developed an introductory object-orientation course which I turned into my first two books, The Object Primer and Building Object Applications That Work. My point is that I built up to writing books. I gained writing experience as a columnist and organized, and proved, my ideas in the form of a professional course. When I approached publishers I had a proven track record, something which greatly reduced their risk.
To gain writing experience you can publish to the web, in local newspapers, in print magazines, or within corporate newsletters. Yes, it's still hard to get published in some of these venues, but it's much easier than convincing a publisher to invest in your book idea.
The next step is to select a publisher, and to do that you need to identify which ones exist within the book category which you'll be writing in. The easiest way to do this is to look at your own bookshelf to see who published the books which you have read.
Having identified potential publishers contact them and ask for their proposal guidelines. Most publishers will ask for a short summary of the book, a detailed table of contents, between one and three sample chapters, an estimate of the page count, a proposed writing schedule, and an estimate of the market for your book. Unless you're a proven author with several best-selling books, you really need to do a good job on the sample chapters. A common mistake is to write the entire book before finding a publisher -- this might work for fiction but for non-fiction I highly advise against it because you risk doing a lot of work only to discover nobody is interested in your book.
Identifying the potential market for your book is critical. You will need to understand what books are currently out there, what their strengths and weaknesses are, and how yours compares. If there are thirty books out there already which are similar to yours then chances are very good you're not going to find a publisher (unless of course you can find a boutique publisher who hasn't yet broken into that book category) because chances are very good that your book, no matter how good it is, simply isn't going to sell. Always remember that publishers are in business to make money. You also need to understand how many people might be interested in your book. Sure, there's over a million Java programmers but only a small fraction of them might buy an Elements of Java Style book for example.
You can usually submit the same proposal to several publishers, but remember that it's a small industry and be judicial about who you send it to. The publisher will invest a fair bit of effort, and money, evaluating your proposal. It's good to have more than one offer, but at the same time you don't want to burn any bridges.
You might also want to consider self publishing the book, either as an eBook or as a print-on-demand book. I haven't tried this yet so don't have much advice for you.
Most publishers will insist on seeing at least a table of contents for the book, which is good because it forces you to actually think through what you're going to do. Some good ideas:
Plan from the point of view of a reader. What do they need to know and in what order do they need to know it.
Stay focused on the topic at hand. Remember that just because you want to write about something that doesn't mean that the topic needs to be in your book, or at least not in much detail.
Look at examples. Take a look at the table of contents from some of the books which you think are well written, and adopt a similar style.
Seek feedback. Show your plan to trusted colleagues and act on their feedback. Publishers get many book proposals every day, so your proposal needs to be top notch. The best way to ensure this is to get several people to review your proposal before you show it to the publishers.
Most publishers have a standard set of contracts. If you're a first time author, chances are pretty good that you'll end up having to accept the standard contract. A book agent might be able to get you a better deal, but after their fee you might actually be worse off. A proven author will definitely be able to negotiate a better deal. I guess that my advice is to stay realistic. The important thing to remember is that you'll make more money because you've written the book, either in increased consulting revenue or a promotion at work, than you will from the book itself.
This section overviews the writing process as I like to approach it. The writing process is evolutionary in nature: you'll do some research, some writing, some more research, some updates, ... and so on. Few people, if any, approach writing from a serial perspective where they do one task at a time and never return to it again once finished.
Here are a few good ideas:
Time to be harsh again: it is highly unlikely that you have anything truly unique to write about. Even if you're writing the very first book about Technology X, the fact is that in the past others have implemented things very similar to Technology X in the past. For example, think back to when Enterprise JavaBeans (EJB) was introduced in the late 1990s. Other than the name, there was nothing new in EJB except the configuration of technologies being deployed. It build upon the Java platform, it supported a layered architecture, it encapsulated basic persistence functionality, it supported (eventually) a flat transaction control model, and it implemented rudimentary security access control. Absolutely nothing new. For example, anyone initially writing about transaction control in EJB should have been referring to previous work done in CORBA's object transaction services (OTS), the ISO transaction standard, and even IBM's CICS environment from the 1970s (to name a few things).
As Newton once said "if I have seen further [than others] it is by standing on the shoulders of giants". The implication is that a good writer must know and understand what has been written previously about the topic which they are focusing on and ensure that they build upon that work. They should adopt the good ideas, best practices, ... etc from that work and provide references to good resources. The references are important for several reasons:
They enable your reader to easily find greater details about a topic.
They dramatically improve the quality of your writing because you can build upon the good ideas of other very smart people.
They show that you potentially understand the topic which you're writing about.
They show the respect to the people who have come before you.
Some good advice:
Continuously research. You should do a lot of research before writing the book as well as during the writing effort (new material is being published daily). I've reviewed several book drafts where the author has missed out on important ideas, even ideas which repudiate their own, because the material was published while they were focused on writing. That isn't a good excuse.
Use the web. There is a significant amount of very good material published on the web (just take a look at www.agilemodeling.com, www.enterpriseunifiedprocess.com, and www.agiledata.org for examples within the IT industry). In fact, for many disciplines the web is the primary source of information, something that is pretty true within the agile software development community for example. Like it or not, if you don't include web resources in your research efforts you will risk missing out on leading edge ideas. Having said that, there is also a lot of poor quality material available on the web as well: you'll need to get good at distinguishing between the two.
Use written resources. There is still a lot of really good material out there in print. Within the IT industry, for example, there is a spectacular amount of information in print on the fundamentals of transaction control, user interface development, database development, networking, security, and so on which doesn't appear in detail on the web. Take the time to look into, read, and understand this existing literature otherwise you risk reinventing the wheel.
You can make your writing efforts significantly easier by setting a common set of conventions early in the process. Most of these issues you will want to discuss with your publisher, but you should consider setting conventions for:
File names. You should have a consistent naming strategy for your file names, e.g. for your documents, images, source code files, .... In the past I've made the mistake of embedding the chapter number in the file names, only to discover that I needed to renumber them when I've rearranged the chapters. However, at some point, usually towards the end of the book writing process, you'll need to embed the chapter numbers into the file names so that the publisher (and any reviewers) understand how to build your book. For example, early in the writing process I have file names such as EnterpriseArchitecture.doc and DeploymentProcess.doc and later I might rename them 06EnterpriseArchitecture.doc, 04DeploymentPlanning, and 09DeployingIntoProduction.doc later on.
Contractions. Do you write "It is" or "It's" Talk to the publisher, although I've found this depends on the individual copy editor (who is almost always a contractor).
References to chapters and sections. E.g. (see Chapter 6) vs. (see Chapter 6, "Agile Architecture")
References to figures. Do you hardcode figure numbers, e.g. Figure 1-3, or do you use Word's caption and references features to auto-generate this information for you? Ask the publisher, they can be very particular about this sort of thing.
References to pages. I only refer to other pages in reference books such as Refactoring Databases. During the writing process I generally refer to other pages with the text " (page XX) " and then wait for the publisher to determine the actual page number during the layout process.
Capitalization. Proper names, such as Scott Ambler or Agile Unified Process should be capitalized. In general, terms such as as "use case" or "use case model" should not be capitalized. In the past, particularly the 1970s and 1980s, it was common practice to capitalize terms such as Use Case Model but this has gone out of style.
Use of commas in list. "One, and two, and three" vs. "One, and two and three". I personally lean towards the first approach, but choose one and stick to it.
References. Ask your publisher for their preferred approach to references. Given the choice I prefer the APA style approach although the IEEE approach is fine too. DO NOT INVENT YOUR OWN APPROACH.
Boxes. Set an approach for things like tip boxes, suggested readings boxes, top ten lists, ...
Other good ideas:
Keep diagrams separate from the documents (e.g. don't embed them into the docs). Your diagrams will evolve in sync with your text. In the past I've embedded diagrams in the Word docs so that I could easily see the diagram as I write, but I've found that the maintenance effort is too much (every time I update the diagram, I'd have to update the doc). Furthermore, most publishers will insist that you have separate files anyway.
Adopt a consistent set of templates. Your publisher should provide you with templates for chapters, appendices, and so on. Use them.
Choose a dictionary and stick to it. I prefer Webster's 10th Collegiate Edition, an American dictionary, even though I'm Canadian. The fact is that American English dominates the computer industry, so accept the fact and move on.
There are several critical things to remember:
You're not a compositor. Don't worry about making your document look pretty, that's what the compositor does. Your goal should be to focus on writing the content of the book and capturing the information consistently.
Version control is your friend. Lock down all writing artifacts just like you would lock down your source code. This enables you to recover previous versions of your work and even recover from catastrophic problems such as a hard drive crash (assuming the version control tool's repository is on another drive).
Get anal about spelling and grammar. This is very important. It may be the copy editor's job, but you don't want to make her life hell and frankly she'll just send the documents back to you all marked up anyway. Worse yet, your technical reviewers will spend an inordinate amount of time giving you feedback about your trivial mistakes instead of on the actual content itself.
You're going to refactor. As you write you're going to realize that you need to subdivide chapters, combine chapters, rearrange them, rearrange the material within a chapter, and so on. This refactoring, which is perfectly natural, will inflict havoc upon your number schemes for referring to chapters, sections, figures, ... Early in the writing process I will have references such as [AM] not  because I know I'll have to renumber often otherwise.
Issues to consider:
I prefer to develop a diagram before writing the text describing it. I've always found that a good diagram will dramatically simplify the writing effort.
Work iteratively. Although I start with a diagram as I write the text I'll realize that the diagram wasn't quite as good as I originally thought and will work on both in parallel
Visio is the way to go for complex diagrams. Some publishers still struggle to deal with Visio diagrams because their composition people work on Macintoshes so be prepared to covert your files over to TIFF or EPS for them (Visio does this easily).
Consider whiteboard sketches for diagrams. I've published several books containing sketches and therefore would argue that it is "socially acceptable" to do so. Furthermore, it reflects the way that people actually work (do you really create pretty Visio diagrams on a regular basis, or do you create sketches to explore ideas). I present some good advice for sketching, including links to tools to help make your sketches publication ready.
Consider following common diagram style conventions. I have summarized style guidelines for software diagrams, in particular the UML; I suspect that most people will benefit at least from the general guidelines.
You're still not a compositor. ;-)
An important part of the writing process is receiving the copy edited version back from the editor. Good things to know:
The copy editor will have fixed any grammar or spelling mistakes that you may have as well as ensured that your use of styles throughout the book are consistent.
Determine whether the copy editor wants you to accept his changes in your documents (via change tracking features in your word processor) or to simply add your own changes overtop of his. Usually the editors want you to leave the changes in so they can see every change.
This is your last chance to make any major changes to your book, although frankly you shouldn't be making major revisions by now without a very good reason (for example the technology has changed yet again).
Given the choice I prefer to get my chapters back incrementally, so that I can work in parallel with the copy editor. This will shorten the time line.
The copy editor is probably right about basic grammar and punctuation 98% of the time. Recognize that there are different approaches to punctuation, and the copy editor may work by different rules than what you prefer. Do you have one space after a period or two? It doesn't really matter as long as you're consistent throughout.
Be prepared to learn the copy editing notation commonly used on paper copies. Although it's common now that editors will mark your work up electronically, some still have their heads in the 19th century.
This is your last chance to get it right, but unfortunately you can make very small changes at this point because you likely won't be allowed to do anything which forces the publisher to repaginate.
Obtain the composed copy. The publisher will send you printed copies and/or a PDF file(s) to edit. If you've been sent printed copies then you'll also be sent a page describing copy editing markup language. It's fairly straightforward although not obvious at first. A better way to work, IMHO, is the work with PDFs and either mark them up in adobe or to simply fill out a spreadsheet listing, by page, any corrections you feel is appropriate.
Get help. Each author should ask friends and family, even non-technical ones, for help -- at this point, the more sets of eyes you have on the book the better. You've likely gone over the text so many times that you're going to miss the simple things that you should be looking for at this point. Provide them with a spreadsheet or form to fill out (feel free to use this one) and the following issues list of things to focus on. Send the composed copy out in batches, if you send it all at once you'll likely overwhelm people. For the spreadsheet, I like to use the format "ReviewerName ChapXX-YY" , e.g. "Ambler Chap01-04".
Combine the feedback. You'll get feedback that you don't want to fix, or repetitious feedback, from the various reviewers. I typically capture the official edits in a single spreadsheet for the entire book.
Send the proposed edits back to your publisher. Some publishers want the spreadsheet, some want marked up copy (this reflects the paper-based approaches of the ancient past, e.g. pre-2004, and I find it really ineffective), and some want both. Make it as easy as possible for the publisher.
Things to look for:
Are the references to other parts of the book correct? e.g. if you reference Section 17.3, does it exist and is it the right section?
Are the references to other writings consistent with what is in the references list? e.g. are the years consistent? Are the names spelled correctly?
Are the diagrams and tables referenced properly? e.g. When you reference figure 9.8, should it really be 9.8 or 9.7?
Are the diagrams the right ones? Is the diagram the publisher thinks should be Figure 9.8 the one that you want them to use for Figure 9.8?
When a paragraph crosses pages, has any portions of it been lost (e.g. did the last sentence on the first page, or the first sentence on the second page, drop off?)
Are the type faces consistent?
Are the terms consistent? e.g. are you using the term "use case" or "use-case" throughout?
Look for double punctuation. e.g. ,, ,. .. and so on.
Is each table/figure referenced in your text at least once?
Are the headings (typically in the page header) on each page the right ones?
The most exciting time for me is when my "authors crate", I typically ask for 20 books to give to family and friends, although the past few years I've been negotiated down to between 5-10, arrives at my doorstep. Your work isn't done at this point, you'll still need to consider:
Distributing signed copies of the book to your reviewers. The publisher should provide copies for this.
Marketing the book on your web site(s), in conference presentations, in training classes.
Keeping track of typos and/or changes to the next edition, if any.
I'd like to thank Bert Bates, William Brogden, Ernest Friedman-Hill, Andrew Monkhouse, Ilja Preuss, Pramod Sadalage, and Henry Wong for their input into helping me improve this article.
This site owned by Ambysoft Inc.