how to write computer books

Top 10 things I love to see in a first draft

When I open a chapter, this is what I dream of seeing:

1. A clear introduction. This is the first thing I see. The introduction should set out the main topics covered in the chapter. It should do so in a way that makes the chapter sound interesting, and so that readers understand “what’s in it for me?”. Usually, you’ll have a bulleted list with 4-6 main topics.
2. Lots of meaningful headings. Next I look at the Document Map to see the structure. I am especially happy if there are about as many headings as there are pages, usually more. Extra credit if the level-1 headings roughly match the 4-6 main topics mentioned in the introduction. Double extra if the level-1 and level-2 headings make sense even if you haven’t read the chapter yet.
3. Appropriate screenshots. You want screenshots to show stuff that looks cool, the result of examples, or to illustrate any instruction that’s hard to explain. These are all good — I can scroll through the chapter and think “we’re doing fun stuff here”. And readers can flick through and feel the same. A screenshot for every stage in an installation wizard or other trivialities is rarely such fun.
4. Cool examples. Show me that the reader will acheive something worthwhile in the chapter. What do you teach readers to DO? Would I want to do it? (If the effort exceeds the output then it’s not a compelling example.) And if you’re getting the reader to build something cool, include a picture will you! Otherwise they won’t know it’s worth the bother…
5. Clear instructions, explanation, and information. Most chapters have (1) instructions — you telling the reader how to do something. (2) explanation — you telling the reader how the instructions worked. (3) information — you telling the reader facts and ideas. Don’t mix them up — readers process the different kinds of information in different ways, so show the instructions first, then the explanation, then the information in separate paragraphs or sections. Separate them with headings.
6. No important buried content. The main points should leap out. Don’t bury a key point deep in an example — make it stand out. The main points should usually have headings to introduce them, at least. It really upsets me when I’ve scrolled up and down a chapter trying to understand it — and then find the most important, interesting point nestled inside a paragraph about something minor.
7. Good use of lists, tables, diagrams. Don’t assume prose is the best way to do everything. Sometimes lists, tables and diagrams work well. But be warned — lists and tables that go on for more than a page won’t make me happy.
8. Practical, actionable content. I don’t want to see much content that the reader can’t put into action in one way or another. This is a book about how to do things, after all. Always write things that the reader can use, not just read.
9. Some wit or humour. We’re human beings too — give us something to smile about and enjoy. That doesn’t mean tell us jokes… but we’ll usually enjoy a witty turn of phrase, a wry heading, or a bizarre example.
10. Lots of code but well explained. If the book is for programmers then they love code. But they don’t love pages at a time. A 20-line or less code block that does something useful, followed by an appropriate level of explanation, will usually cheer me up. More than a page of code at a time and I’m weeping.
11. Simple but correct English. I want the English to be clear and not full of complicated, jargon words that I have to unpick. Relevant technical terms are great. Long BS words and complex sentences designed to make the writing sound clever will end in tears. 2-3 syllable words and max words per sentence of 22 is a good guideline.