PragProWriMon
Pragmatic wants November to be PragProWriMon, something of the non-fiction alternative to NaNoWriMo, or National Novel Writing Month. It’s a great idea. The best way to actually write anything is to get in the habit of sitting down and typing. Conversely, the best way to stop writing something is to break the habit, even for a couple of days.
There are other places to go for inspiration on sitting down and writing (I’m kind of partial to Merlin Mann’s epic about making the clackity noise). But I do have a couple of disjointed things to say about writing technical books for programmers.
Write about something you’d love to learn more about
I’m completely confident in the following statement: you will need to learn new things in order to write a complete technical book. Even if you are the lead maintainer and undisputed overlord for eternity of an open source tool, there’s going to be something going on in the ecosystem that you’re going to need to know more about when the time comes to write about it.
I’m also completely confident in this statement – if you are willing to learn new things, and learn them quickly, you don’t need to be the lead maintainer and overlord to write a good technical book on a topic. (Though it does help tremendously to have a trusted super-expert as a technical reference.)
Pick something that you are genuinely curious about and that you want to understand really, really well. It’s painful to write even a chapter about something that doesn’t interest you.
I’m sort of a test subject for this because I’ve had wildly varying levels of expertise on the subjects of my books when starting writing. For the Jython and wxPython books, I was brought in to help out a co-author who was the true technical expert and I only had a little bit of experience with either one going in. In contrast, the Rails test stuff I’m writing now really is the stuff I’ve been working on for the last few years.
The main weaknesses of not being a true super-expert going in are a) it’s more work and b) the nagging feeling that you’re making mistakes that you can’t see. But there’s an advantage, too. The closer you are to learning the material for yourself, the more sympathetic you are to a novice’s struggles to control the material. The key is being able to explain the material clearly and interestingly, and being clear about what you know, what you think, and what you struggle with. I would totally buy a book like “Watch a Ruby programmer struggle to learn Scala” – I think that would be an interesting way to learn from somebody else’s mistakes.
Have an opinion
“A movie is not about what it’s about; it’s about how it’s about it.” – Roger Ebert
“One of the operating assumptions of this book is that you either own Macmillian’s The Baseball Encyclopedia or aren’t interested in what it has to say; in either case you don’t need me to tell you what an outfielder’s assist totals were.” – Bill James
I love that random Bill James quote so much that a paraphrase of it tends to sneak into my books somewhere (along with a reference to Scott McCloud’s Zot!). The point is to have assumptions – you can’t explain everything. It would have been easy for James to clutter his book up with even more numbers that most of his readers already knew or could look up, but he elegantly sidesteps that problem.
My Jython book suffers because we never really decided whether it’s primary audience was Python programmers or Java programmers. The wxPython book is pretty clear in assuming the reader already knows Python. (We actually wrote an introduction to Python, but it was too short to be useful and ultimately cut it). The Rails testing book is clear both in assuming that the reader already knows Rails basics, but also in assuming that starting with the Rails core tools is the best way to get introduced to testing Rails programs.
You have opinions about the tools you want to write about – how to use them, when to use them, when not to use them. Your book needs your opinions (even, I’d argue, if it’s got a strong reference component) otherwise it’s something anybody could write.
That’s long enough for now.