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.