writing tech books: write what you don’t know

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.

4 comments to writing tech books: write what you don’t know

  • Worthwhile insight, ML.

    It’s also implicit in your angle on technical writing that you *don’t have to be a professional writer* to write.

    For many of us, it’s considered a realm for language majors (ie, English) who happen upon technology, when that’s not the case. It’s mostly technical people attempting to articulate their experiences and thoughts.

    That’s what makes your point interesting. While the best books on software X might be by the creator and developer of software X, for most readers, the person learning the ropes on software X might provide the more useful angle.

  • I agree to some extent, but also disagree – you must have some foundational knowledge and experience to write a good technical book. No, you don’t need to be the world’s foremost expert on the subject, or even competent enough at the start to write a great book on the topic. You need to know what you don’t know, and do the necessary research and experimentation in the writing process to obtain the needed knowledge in those areas. But you can’t start from 0 and get a good technical book done, it would take so long to obtain the needed knowledge to reach that level that it would be obsolete by the time you finished. Michael didn’t start writing about NetFlow having never administered a network or used NetFlow before, or the FreeBSD and OpenBSD books before ever installing BSD or administering a server – that would be a recipe for a horrid book, or one that took so long it would have to be largely rewritten to be relevant.

    That said, being a contributing author on one book, and writing the bulk of another, in my experience there is no better way to become an expert at something than to write a book on it. Good technical writers ask themselves the same questions when writing that readers will ask themselves while learning, and are able to provide those answers. In fact the writing process has been a good way for me to find out how much I don’t know in some areas and fill those gaps. When I started the pfSense book, there wasn’t another person on the planet with close to the same level of deployment, configuration, troubleshooting, and support experience as I had at the time, being one of the founders of the project, and making a living doing those things. But there were still many things I learned in the process of writing the book in answering the questions I had myself, while evaluating things thinking as I would as a reader rather than an author. Judging by the reviews and success of the book, that approach worked well.

    If you have some level of knowledge and experience in a subject, but not enough to competently write a book, don’t let that hold you back from doing it as long as you have the drive to put in the work to figure out everything you don’t know. If you’re a help desk tech who barely knows how to log in to a server and think you can write the next great server administration book starting today, you’re sadly mistaken.

  • Chris is obviously trying to make me write all of the “how to write a tech book” blog posts at once. 🙂

    I would say that “helpdesk to FreeBSD expert” is not an incremental advance. Going from “person who runs BSD” to “BSD master” would be an incremental step. Look at, say, Joseph Kong. He wrote the book “Designing BSD Rootkits” and is now doing the NSP “FreeBSD Device Drivers” book. Increments. Small increments.

  • […] vore att ha för låga ambitioner. I stället siktar jag på något den fantastiske författaren Michael W. Lucas skrivit om:One of the old cliches about writing is that you should “write what you know.” In tech writing […]