For some reason, a lot of technical writing is still done as if the reader didn’t have access to the Internet. Having written two books (Mixu’s Node book and Single page apps in depth) in the past year, I’ve had some time to think about what good technical writing might be. There are several things that could be improved:
1. Assume the reader has Internet and Google capabilities. Skip the parts that are covered better elsewhere or that will go out of date quickly. For example, installation tutorials are never up to date. I’ll generally skip the sales pitch for the technology as well, since I’m here to tell you about the tech, not sell you on using it.
2. Keep it short and to the point. I hate books that try to be cute or clever with me – if I want a story, I’ll go read fiction. Similarly, don’t surprise the reader with irrelevant sections. Just because you wrote it doesn’t mean it should exist. I keep a crap file where all the useless text goes, and I usually have a couple of chapters worth of text that I delete. I’ve written several chapters on the history of a piece of tech, and always deleted them in the end.
3. Use teasers, lists, tables and code blocks. Assume that the reader can get bored quickly, so throw in something interesting quick (a teaser) and support skimming readers with subheadings, lists and other structural elements.
4. Don’t treat everything as equally important. The easiest way to write a book about a piece of tech is to take the API, and then cover each and every function in it. It’s also the worst possible way to do it. Unless you are writing the API docs, you should avoid talking about everything and focus on the interesting parts.
As a reader, if I want to find out more, I can always read the API or code. What is much more important is understanding what are the neat things that I can do with the new tech, what kinds of patterns are common in using it and why you as the author think they are good or bad. Talk about how the pieces fit together. If everything is equally important, then nothing stands out. I like getting the author’s angle on things, even if I might disagree with their choices, I still feel like I gain insight.
5. Give me a choice in formats. Provide HTML, PDF, epub and mobi versions of long texts. Converting html for the Kindle just requires running one command with Calibre, so I wish more authors gave me the option to download their writing. For example, I wish I could get Google’s tutorials for Android as a Kindle mobi book, since that’s how I like to read long form writing.
6. Help me navigate. Often, when I like what I read, I’ll want to read more. Don’t force me to go page by page through your writing. If you have a blog, have an archive that can show all the content, and let me get an idea of what else you’ve written about at a glance (a most popular list always helps).
More about writing: