designing a tech book

So, you’ve figured out some incremental advance in your own education that you think would make a good book.  Now you grab your keyboard, open a text file, and start typing.

Not so fast.

Just as a large programming project has a specification, a book has a design.  You can start churning out text just as you might churn out code, but eventually you’ll have to stop and think about what you’re doing.  Time spent designing your book beforehand will pay off in the actual writing of the book.  Here’s how I do it; other authors have their own methods, of course, and you should do whatever works for you.

When I consider writing a book, one of the first things I do is write down what I think should be in the book, without any detail whatsoever.  If I’m writing a book on a particular operating system, it should include installation instructions, guidance on the community around the operating system, the sysctl setting that bit me yesterday, upgrade instructions, and so on.  Everything that I think of, both large and small, trivial and vital.

Keep this list with you as you experiment and learn.  When you think of something else that should go in the book, add it to the list.  No detail is too small.  If your idea is strong enough and sufficiently broad to carry an entire book, you’ll eventually have 30-40 pages of “stuff.”

Take a couple hours and try to sort this list into broad categories.  Move details around from category to category.  See what facts they belong with.  Those categories will eventually become chapters.

Now comes the annoying bit.  Think about what the reader needs to know before he can understand one of these sections. A properly designed book can be read from beginning to end, each paragraph presenting the reader with new knowledge that is built on top of what he’s read before.  This order of information is vital to reader comprehension.

For example, look at Absolute FreeBSD.  In my original notes, I had a category called “Managing Disks.”  I had another category called “Security.”  The book needed to cover both topics.  But what order should they go in?

  • To use some advanced security tools, such as jails, the reader must be able to manage system disks.  Put the disk management section first.
  • The first thing a sysadmin needs to do is create a nonprivileged account for his routine work.  User management is definitely part of security.  The security section must go first.
  • Encrypting a disk partition is part of security… and part of disk management.  You need a decent understanding of both before you can manage an encrypted partition.
  • You don’t have to understand security to manage software RAID, so it’s irrelevant either way.
  • The reader needs both before he can realistically upgrade his system.

The solution:  split the disk category into Chapter 8 and Chapter 18, and split security into Chapter 7 and Chapter 9.  Repeat this process for every category in your list.  Some categories will be too small to make up an entire chapter, and you’ll find that you have to shuffle them into another chapter.  User management could have been its own chapter, but it was small enough that I added it to the first system security chapter.

Assess each category based on what the reader needs to know before he can understand it, and place it appropriately in order.  Spend some time on this; fixing ordering problems is easiest before you start writing.

Then arrange topics within categories.  My first security chapter included both user management and file flags.  Which one should go first?  Separate your notes into further piles within each category.

Now that you have a list of chapters, and a sample of stuff in each chapter, fill out your chapters.  Your long list might have said “add users” and “disable users.”  Now that you have both notes side-by-side, you can see that you should probably add “remove users.”  Read man pages on the topics.  Fill in stuff that you should cover now that you’re being methodical.

If you have to move chunks from one category to another, that’s fine.  Pick up the whole hierarchy and move it.

Eventually, your mass of points will become a design for your book.  Set it aside for a few days, and come back to it with fresh eyes.  Are any of the chapters far too short?  Combine them.  Do any early chapters require knowledge that you’ll cover in later chapters?  Rearrange them.  Did you miss any topics?  Add them.  Are any of these topics redundant, uninteresting, or otherwise bogus?  Cut them.

These days I do all this rearranging using OpenOffice and bullets.  That’s not ideal — I’d like to be able to expand and shrink chapters, and have checkboxes for each item so I could record when it was done.  I used yank for several years, but it no longer builds and I haven’t found anything equally flexible and simple.  If you have a comfortable tool, use it, but the point is, you don’t need much more than a text editor.

With careful thought, this will create a book outline that’s both useful to you and (comparatively) easy to write.