How to write a technical book
/
So, I’m loitering on this forum and Tamás was asking if anyone had any tips for first time technical writers. I sent an email response and then I decided that the whole world should have the chance to read my words of wisdom…..
I’ve written a few books over the years. I can confirm that it is not a way to get rich, but at least it is a hobby that doesn’t run at a loss. I’ve self published and used a publisher.
It is surprising how many typos get through when you self-publish. You have to work really hard (and show your text to loads of people) to get the same level of mistake detection as you get from a good copy editor.
A good technical editor adds a huge amount to a text. If you are self publishing see if you can persuade someone to take this role. Perhaps offer to pay them with a signed copy of the book. Or a nice piece of cheese.
Lots of pictures can make your book file large and unwieldly, but to the reader opening a book and seeing a pair of pages of dense text can be a bit demoralising. Settle for diagrams and cropped screenshots that might be less version sensitive.
Don’t be afraid to talk directly to the reader. When I started out I tried really hard to put things into the third person for no good reason. It’s painful and people don’t like to read it. Address the reader as “you”. Have a conversation with them. And for projects you can say “We are now.....”
Never say something is easy. It trivialises the point and makes the reader feel stupid if they don’t understand it. Instead tell folks how powerful the technique is and how useful it will be once they get it.
Context is key. Don’t tell the reader how a for loop works, tell them the situations in which a for loop would be useful, with a side order of when not to use them and how they can go wrong.
Readers love narrative. If you can make the text into a story or journey that will be a huge win.
Round things off at the end and provide a trajectory for the reader to take what you’ve told them and go further.
Use verbs in chapter titles – “Make a whatnot” is a quick way of setting a context. Just giving the name of a tool or technique as a heading won’t help the reader as they don’t know what it is. If you want to name the technique say “Make a whatnot with a whatsit”
Treat your first pass of the material as the “ore” that you you’ve mined. You then have to refine it into the finished content. Don’t be afraid of making huge changes at this point. You might have to rearrange or dump large sections until it feels right. I find that I have to “go and live” in a chapter for a week or so until I’m happy with the sequencing and content.
I went to a session about writing a long time ago and they talked about “Killing your favourite children”. By that they mean that you might have a chunk of text that you really like the look of, but it doesn’t really fit the context of the piece that you are writing. In that situation you need to dump the text that you love.
Never really throw anything away. I keep a folder called trash where I put stuff that didn’t fit (see above). Maybe it will come back as a blog post or in a different section.
Look at writing tools. I’m playing with something called Scrivener (https://www.literatureandlatte.com/scrivener/overview) which I quite like. It makes it very easy to organise and sequence elements (which can be given separate synopsis sections). It also has very advanced output options where the same text can be compiled to generate different output formats. I’m hoping that it will make it easy to make epubs, word documents and html pages. It’s looking promising so far...
Treat what you have written as collateral that you can always find an outlet for. This email is going to turn into a blog post 😊 - and it did
