Category: writing

So how does the traffic I get here compare to an established Web site, like the OpenBSD aggregator undeadly.org? Undeadly linked to my OpenBSD story…

Can you guess when?

No, they weren’t the only ones. But 6 of my top 10 referring URLs were in undeadly.org. The lesson is, do not feed the puffer fish. They will swarm and eat you like the tender tasty morsel you are. They even crashed my helpless little server. (Admittedly, I’d done terrible things to the server configuration, including twaddling knobs labeled DO NOT TOUCH, but that’s not the point.)

This is not the first spike I’ve gotten; my BSD/wikileaks article dang near went viral. So, another lesson I might learn is: if you write something that’s honestly interesting, people will find you. You really don’t have to break your back promoting it. Lots of writers babble about self-promotion, but most of it is an example of “solving the wrong problem.” Rather than pimping what you’ve written, make your work more interesting.

But that’s too positive for me. I think I’d rather just fear the Puffy.

I’ve started the next book for No Starch Press. There’s an outline, and I’ve written both the introduction and the afterword. All that’s left is the hard stuff in between, twenty-some chapters of it.

Where to start writing? That’s easy: First, I write the stuff that’s most likely to make the book fail.

Every project has easy parts that are fun and go quickly. Those are the tasks you’re most familiar with, that leverage your existing skills. Then there’s the parts that require you to learn new things, or demand that you actually spend time and energy breaking them down so others can understand you. These are the parts of the project that are most likely to make the project fail. I want to get those parts over with as quickly as possible.

If the entire book is going to collapse because four chapters are impossible to write, it’s better to know that up front than after I’ve written the eighteen easy chapters leading up to them. I’m writing about 500 words an hour on this part, where I normally write 1000 words an hour. It’s drudgery, but they’ll get done.

I’ve seen a lot of IT projects fail by spending their initial burst of energy on the easy stuff. If you do the easy part first, the hard part gets time to grow in your mind. You’ll spend energy dreading it. Worse, the time you spend doing the easy stuff might be completely wasted — after all, if you can’t do the hard part, then you have to throw everything else away. You can always do the easy part after you succeed at the hard bit, and it’ll make the rest of the project go more quickly.

Now if you’ll excuse me, I have to finish this section of this chapter tonight…

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.

This is the first of an irregular series on writing tech books. I got the idea from something Richard Beijtlich wrote in a review years ago.  Unfortunately I cannot find the cite, and spending the day exhaustively reading my old reviews is psychologically unhealthy, but he said something along the lines of “tech authors could do worse than see how Lucas does things.”  I believe that the average quality of writing in tech books is abominable.  Perhaps I can pull those standards up.  By the ear, if necessary.

So, where do you start to write a tech book?  Start by deciding what you want to write about.  One of the old cliches about writing is that you should “write what you know.”  In tech writing this is not only wrong, but actively harmful.

Writing about something you already understand, in a way where you can communicate your knowledge to the uninitiated, is hard.  You brain contains a lot of information, and it’s all jumbled together, interconnected.  If you think your desk is messy, your brain is worse.  Teasing out what you know, and how you know it, with the necessary context to explain it to someone else, is hard.

Instead, I recommend writing about something you want to know about.

When I started writing PGP & GPG, I certainly wasn’t an encryption ninja.  I run BSD servers, but when I started writing the FreeBSD and OpenBSD books I didn’t possess the breadth of mastery necessary to write a book about either.  I learned as I wrote the books.  The books actually became structured learning — self-directed, self-designed, at my own pace, but highly effective.

As you learn the topic, take notes.  Write down what what you must do to accomplish a task.  Use script(1) and screenshots.  Get a paper notebook, keep it by your computer, and scribble notes in it.  This gives you a student’s perspective.  As you learn, you’ll see how this new piece of knowledge attaches to the other knowledge in your head.  Notice those mental connections as they happen.  Those are things you should mention in your writing.  Part of your job as an author is to help the reader make those connections inside his own head.

Note that you should choose a topic that is an incremental advance on what you already know. You need a base of knowledge to learn from.  Trying to write on something that seems close to to your skill set, but isn’t truly incremental, will fail.  Suppose I wanted to write a book on Perl.  I write Perl, but my code is appalling.  To write the book on Perl would require that I first become a programmer, then learn Perl.  This is not an incremental education.  If I want to write a book on, say, Tuvan throat singing, I would need considerably more lead time and a much higher budget.  (Plus completely deaf neighbors.)

By writing about the next step in your education, you’ll expand your own knowledge about the topic.  I might not have been a netflow expert when I started writing Network Flow Analysis, but I sure know a heck of a lot more about it than I did when I started.

I’ve surrendered to last years’ (or was it the previous year’s) information fad:  Twitter.

You’ll find me at:  http://twitter.com/#!/mwlauthor.  I believe that tweakers call that @mwlauthor?  Anyway, you can expect random crap there as I figure out what I’m doing with it.

I should say right now:  I don’t follow everyone who follows me.  I can’t do it with blogs, I can’t do it on Facebook, there’s no way I could do it on Yet Another Social Media Platform ™.  And the idea of constant interruptions and near-real-time interaction is, frankly, overwhelming.  Authors don’t scale with their readers, sorry… I still run under the Big Giant Lock.

I will click through and look at people as I have time, though.  It’s nice to be able to see who reads my stuff, and what sorts of things those people are interested in.