So you are writing a tech book with sample code…

This post is the result of frustration I have with code examples in some tech books. It is in your interest as an author to follow these rules as it might make your book relevant for longer and result in higher sales of your work. I know, I know, all these rules seem obvious but for some reason the number of books that don’t follow these rules is still “too damn high” to paraphrase a popular maymay so I guess someone has to say it.

• Follow Joel’s test rule #2. Getting your sample code to run should be a single action. Yeah, I get it, setting up dev environments esp. on machines you don’t have access to is annoying. But you know what’s also annoying? Trying to learn something new and then spending half of the day trying to figure out the build system of a platform or language you’ve never used. It’s even worse when your book is say about front-end JS but your code samples use a back-end written in say Scala. If you do this, I might make a voodoo doll of you.
• If you follow the previous rule, you might dedicate less of your book to environment setup. No one likes books where a significant portion of the book is dedicated to environment setup.
• If your platform has a package manager and your sample code uses some third party code, use said package manager.
• Your book will have to include some code in the book. Your book shouldn’t contain any code that is not somewhere in the samples.
• Host the code on a code hosting site (CHS) and not on your personal site or your publishing company’s website. Why? Odds are pretty good that as time passes, your sample code will require some fixing. By hosting it on a CHS, the community is more likely to take over, bugs are more likely to be fixed and required changes are more likely to be integrated. Ideally your publishing company should have an organization profile on your CHS and all books published by the publishing company should be linked in said profile. This is marketing of sorts for all books published by your company.
• There should be an obvious correspondence between a chapter in the book and “chapter” in the sample. E.g. chapter 1 should have a corresponding directory containing the code for chapter 1. Each code chapter should have two projects, one which is the“solved” project and one which is a scaffolding for people who want to implement said project themselves but just the interesting parts.
• Your samples should take advantage of latest progress in development on the platform. E.g. if you are writing a Swift book and your book doesn’t include a Swift playground you might be doing it wrong.
• Try to follow [literate programming](https://en.wikipedia.org/wiki/Literate_programming). If there is one place where literate programming should be used, it’s here. Explain why you made some decisions, esp. if there were several possible solutions and double esp. if they do not follow something else you’ve said in your book.
• In general, your book should provide the 30k foot view and your sample code should provide the context.

Remember that if your book sells 1000 copies and each reader spends an hour trying to figure out the dev environment, you’ve wasted 1000 man-hours. Just think about how much you, a ninja-rockstar-wizard-artisan, can propel humanity forward by saving thousands of hours for your readers. And you are a ninja-rockstar-wizard-artisan, aren’t you, you did write a book after all.