Writing a Programming Book in 2021
jmtirado.net
jmtirado.net
* Start by blogging. Try to get thousands of daily pageviews with an average time on page > 5 minutes. Objectively verify you're able to write content that's engaging.
* Try to fill a niche. My book is focused on practical advice for getting productive with Spark using the Scala API quickly. There are other books that cover theory, discuss all 4 language APIs simultaneously, and are API documentation narratives (e.g. Chapter 4 will cover all the DataFrame methods in alphabetical order). Most people don't have the attention span for huge books.
* Target middle school reading level. Short sentences & simple words. Technical audiences want information and don't care much about literary prose.
* Organize your code snippets in a repo, so it's easy to update your book
I got some offers from publishers, but went the self-publishing route cause I didn't think that a publisher could give too much valuable feedback on such a technical topic. Lots of my blog readers told me my blogs are easy to follow, so I felt confident I didn't need a professional editor. Publishers pay 20% royalties and self publishing lets you keep 80%+, so you should only go with a publisher if they can add that extra value.
Writing a book was a great experience for me. It's an easy way to train folks who are new to Spark. Several folks have emailed me, told me they can't afford the book, and I've sent them free copies. Don't think writing books is a great way to make money, but it's great if you have altruistic motives.
[0] https://gabrielgambetta.com/computer-graphics-from-scratch/
It’s great that the book is improved, but that delay is a killer.
I've written two tech books, one python and one Go.
Not have earned me much more than Apress was offering!
I'm based in India though, so $ to Rupee conversion is helpful for me.
My books are pay as you choose. So if those who can't pay can download my high quality book for free. Total readers till now for Go book has been more than 6k!
If you self publish you can contract your own professional editor or reviewers. It's worth doing if you're spending significant time/money in the book &/or marketing. Some popular tech book publishers crowdsource their editing by giving free copies to people interested in editing.
Also, don't bury the lede, but put the main points in the first paragraph, then elaborate on them throughout the rest of the essay.
The Abstract in academic papers is a good example - state the problem, explain how you addressed/explored it, and report your conclusions. Don't bury your conclusions in the paper, but use the paper to elaborate in detail on how you arrived at them.
As for targeting middle school reading level, Scott Adams has a good writeup on exactly how to do that:
https://www.scottadamssays.com/2015/08/22/the-day-you-became...
As a non-native English reader, yes please! Also: Please keep it short.
FWIW, I think this almost always bad advice. Being your own editor is a bit like being your own lawyer - even if you have the right skills you don't have the right perspective.
It's obvious when something is desperately in need of editing. What's less obvious is how much better something "ok" could be with a good editor.
Not saying that you are wrong, more that there are legitimate reasons why an editor might not be the right way forward.
I think this is true, and certainly didn't mean to suggest otherwise. It's just that "a (good) editor wouldn't improve my output" is approximately never true.
Whether that improvement is worth whatever it costs you to get it is a separable question.
I hired a freelance editor to help me with my blog, and it was the best money I ever spent for improving my professional writing.[0] You can get a good editor and still self-publish.
If money's tight, there's still substantial value in just having an editor review a portion of your book and telling you about anti-patterns in your writing.
Is it though, or is it merely a century of the professional publishing industry justifying its necessity?
Neither Plato, nor Nietzsche had an editor. Now those are just two historical examples two and a half millenia apart, but this group also includes any author in between these two.
I think many technical books are written to act as a 'proof' that the author is credible and knows their topic well rather than as an exercise in serving the reader or an attempt to make money. Tech authors know that they've not going to make much. It's more an exercise in vanity and improving job prospects. The author doesn't really need to be right. Especially "Beginner's guide to X" or "Learn X in 24 hours" books, experienced and knowledgable developers won't be reading the book to criticise it, and new developers who buy it won't know it's poorly written, so an author can write any old junk and still claim to be an expert. Consequently I've stopped being particularly impressed by people who have authored books on their resume.
This is why I'd be very hesitant to self-publish a technical book, even though for fiction I think self-publishing is the right decision 99% of the time. We all make errors, even those of us who do know what we're talking about, when you get to the scale of 100+ kilowords. For a novel, a decent copyeditor can fix up the production values well enough; for a technical work, you would hope the publisher assigned some people to check the work.
Depends upon the publisher too, whether they are interested in publishing quality books or have a quantity policy.
>We all make errors, even those of us who do know what we're talking about
I was hesitant to write a book for a long time because I thought I wasn't good enough. I still think I have a long way to go, but I've grown better as a writer with experience. Feedback from users have caught many issues and helped me improve the content.
That's what technical reviewers do. I did it back in the early 2000s. You get sent a copy of a few chapters, and it's your job to review the code and explanations to find errors. It doesn't pay very well though - you get your name in the front, and a free copy of the book, but nothing much else.
Well... in theory they should be. I published a book a while back through a publisher, and they assigned me a copy editor and a technical editor. The copy editor was amazing - it was clear she didn't understand any of the technical details, but she spotted flow errors and minor grammatical mistakes in dense technical prose. The technical editor, on the other hand, seemed to have (maybe) skimmed over the content and his only feedback was that he didn't like my writing style very much and left it up to me to verify all of the technical content. I did take it seriously, though, and I am proud to say that very few technical errors have been reported.
So now my name is attached to incorrect information, and occasionally someone will message me and tell me why I was wrong and I have to message them back and say, "well I told them to fix it but they ignored me".
Not to replace human review but should catch a lot of mistakes
And it was out of date very quickly.
This is a problem with "then-hot" technologies. A number of years back, I was approached by a technical publisher to do a book on OpenStack. I wasn't the right person anyway and passed. But even if I had been, by the time a book would have realistically gotten to market, say 12-18 months, it would have been 3 versions back of the current project.
He knew crap about programming. Was an excellent writer.
-- Geoffrey Hinton
I've found that Hinton's experience with publishing holds doubly true for technical interviews, and am always surprised often people in tech refuse to question their own interview process rather than assume that everyone that doesn't pass it must be an idiot, independent of your prior expectations.
While it is very possible that someone who is a great writer on technical topics is not a great match for your team, I really don't believe that this person "knew crap" about programming. It is virtually impossible to write well about a subject you don't understand.
Again, it wouldn't surprised me at all that an expert on a topic might not be a good fit for your role, take Scott Meyers as an example. He's frequently admitted that he has little software engineering experience, and is not a software engineer. You should probably not hire Scott Meyers as a software dev. But if your conclusion after interviewing him was that he "knew crap about C++" I would read that as an implicit critique of your interview process, not Scott Meyers.
Based on my experience interviewing, the vast majority of data scientist interviewers would quickly write-off Hinton as someone who "knows crap" about data science because they very likely would not understand the answers that Hinton is giving.
Unfortunately, in tech hiring these days, true expertise is far more often then not a liability.
My baseline test is to swap keys and values in a [hash/map/dictionary]. In any language of their choice. So [a=>1, b=>2, c=2] Becomes [1=>a, 2=>[b,c]]
75% fail completely. Some struggle but pass.
Others complete it in a minute and are confused as to why such an easy test.
And the (rather big) publisher didn't seem to care at all.
10 books from an author of technical books is a negative signal. There's not a lot of money in writing technical books so there's an incentive to pump out books without concern for quality. I remember trying to learn C++ in the 90s and nearly every book I read was complete garbage (the authors seemed to think that C++ was C with different comment syntax and using cout << in place of printf). It wasn't until I read the first STL book that things finally clicked.
For some of them, I started self-publishing with leanpub and was later shepherded into the publisher, and I got the impression I could make at least the same amount of money on leanpub.
In college I was nearly thrown out of my math major, after giving no evidence of having started a year-in-a-semester modern analysis course, with three weeks to go. (I had been busy with a disastrous International Economics computer simulation using Fortran punched cards. Why, when Dukakis ran for president, did no one ask if "the world blew up his year?") I am forever grateful that "Baby Rudin" is such a thin book.
A minor in English taught me that genres are not inevitable. They are cultural choices.
Every year I get more comfortable recognizing I'm neurodiverse (substitute your favorite ADHD acronym) and so are many of my best students. Recognizing this makes me a better professor. Math notation, for example, is simply someone else's bad computer code. Don't blame yourself as you struggle to read it, and realize that everyone who succeeds has vivid daydreams that bear no resemblence to the bad code.
I loathe nearly every programming book I've ever read. I live in fear that I'll turn the page and be writing a music player. What's that nugget about "never write a language for someone in their first week?" REPL examples always include all beginner "bird track" prompts, when anyone with an aesthetic sense customizes their REPL in the first week to hide all noise and syntax-color output. When I'm feeling an ADHD haze I can barely find the code samples on a programming book page.
What I've learned as a professor is that everyone feels this resistance. Some acknowledge it. Planes don't crash because we minimize this resistance in the cockpit. The neurodiverse are the canaries in the mine shaft.
I've learned dozens of languages, and bought countless programming books. "The C Programming Language" by Kernighan and Ritchie remains my favorite, a mercifully thin book like "Baby Rudin".
Learning a language quickly, one learns how each chess piece moves, and still wonders how to put together programs effectively. Just as the greats in any intellectual discipline insist on only reading original works, the most gifted programmers learn by reading code.
I also attempt to learn human languages as a hobby. The great difficulties I experience give me insights into teaching. What is most effective is a staged progression of readers, with parallel text nearby, till one can learn to read unassisted in the language. If the content can be anticipated (such as the wonderfully repetitive "Sapiens" in various translations) all the better. If there's also an audiobook, all the better.
A programming book should teach a language through a sequence of small, complete code samples, so clearly delineated that a scuba diver 30 meters deep can work out what's the code, what's the blather. The main activity of reading the book should be puzzling out how each code fragment works. Skip the "word problems" and focus on simple combinatorial tasks that exercise the language.
The other piece of advice I have is: hire an editor and fact checker. The last thing you want to do is put substandard quality content out there filled with bad grammar and errors. This post seems to suggest that by self-publishing, the author did the task of editing themselves. I would say this is not advised if you want the best results. Hire a third party to do this work for you instead of doing it yourself. They will bring a fresh perspective to your work and help you see things that you cannot.
I've seen a lot of blog posts written for this reason, and they're all pretty crappy. I really hope that wasn't seriously a reason to write a book.
With that said, I have read/watched tutorials by people who just learned something and the empathy level to beginners is really high. That's something that can be missing with people who have years and years of experience.
1. It's problematic. Why are we assuming that an old woman can't also be a badass programmer? Plenty of CS luminaries (a) were women, and (b) had kids (c) who themselves had kids, and therefore are someone's grandmother.
2. Your audience isn't necessarily non-technical. Generally your audience is going to be someone who's qualified to take the course. Which means that a good explainer is going to, as you said, have a high degree of empathy to beginners... but not explain things at such an introductory level as to leave people bored.
3. I don't agree that people who can't explain things well to non-technical people don't know their stuff; they lack an important skill that could make their knowledge far more useful to humanity, but that's a different claim from saying that the knowledge doesn't exist.
Attributed to Einstein: "If you can't explain it to a six year old, you don't understand it yourself."
I've always thought that was a better version. But this was never a comment that you should explain things as if your audience was a six year old. Part of communications skill is the ability to pick the right level for whatever your audience is. This quote is much more literal - it's saying the if the range of people you could explain this too doesn't include small children, there is more for you to understand.
For what it's worth I disagree with your (3); it's not just about communication - people often feel that they really understand something when they have a handle on a lot of technical details, but this isn't true. There is a deeper level of understanding that will let you synthesize this and find the real core of what is going on. I've found it to be universally true that if someone cannot do this, however awkwardly communicated, they don't understand the subject as well as they think they do.
This happens with PhD students and "sr" engineers all the time. They may have spent the last 6 months thinking deeply about an area, and when you ask them to explain it to an "talented outsider" they can't. A few years later if you ask the same thing their answers will be much better, because they understand much better.
ِYou don't, really. Studying physics and cosmology has almost zero instrumental utility (except signalling, where I don't think it's worth its measly returns, and contributes little to the society). The child doesn't know this, but you do; That's why you don't know that much about the topic in the first place. Curiosity is as much about pruning unproductive lines of learning as it is about trying new things.
Here's a better quote (also sometimes attributed/misattributed to Einstein) – “Everything should be made as simple as possible, but no simpler.”
The table of contents is typically not an index. An index is something else found at the end of the book.
But I want to say that I wish the credibility is in reverse. You should first be credible enough for writing, then you can boost it further for having it finished and well received. Just finishing a technical book is not enough.
I am too finishing a self published book[0] so I am very interested in other self-published cases. I miss some sales numbers in the article or advice on marketing strategy.
If someone is interested, I just shared how the first month of selling went for my book[1] (spoiler: pretty well for unfinished book). I will continue doing this, because I think it's super helpful for others thinking about it.
Writing a good book is HARD. Marketing it might be even harder. Most authors will be net-negative considering salaried work, so share your numbers!
[0] https://deploymentfromscratch.com
[1] https://www.indiehackers.com/post/today-is-my-first-ever-gum...
Those "self-publishing companies" are often next-generation vanity press. Then again, bottom tier traditional publishing— and the dangerous part is, this includes bottom-tier deals from "Big 5" imprints— are basically vanity press as well.
The number of first-time authors who get traditional deals actually worth taking (the kind that come with 6-figure marketing budgets and TV spots delivered in-hand) is probably in the double digits per year— it's not that hard to "get an agent" if you're willing to take abuse, but 98% of literary agents have no real connections but serve as an HR wall, existing solely to filter out the deserving perma-slush, that will probably be replaced with machine learning algorithms soon.
Publishing gives writers a possibly necessary but very unpleasant introduction to the reality of commerce— there are so, so many people out there looking to get as much as they can (money) and give as little as possible. This applies when you pay thousands of dollars to a "self-publishing company" and get work (cover design, editing, et al) that a high schooler could have done... but it also applies when you sign away your rights to a "Big 5" for a piddly advance and no marketing.
I think the game's very different for programming books than it is for, say, fiction. Generally, people don't write books about Python because they think they're going to quit their day jobs. At the same time, people who can write even passable programming books are fairly few in number... whereas people who can write passable novels that could in theory become the next 50 Shades are commonplace (although people who can write good novels are very rare).
It's impossible to say what it requires not to get scammed in publishing— you have to take some risks, and who can say what risks are right to take?— but a good first step is to accept the very real possibility that you do everything right and still don't sell more than a few dozen copies. Sometimes terrible books sell (50 Shades) and sometimes great books go ignored for thirty years.
You can write in Markdown, and sync with git. You can set a minimum price, but in our experience people often pay more.
A couple of notes:
1. The ability to have a book be "in progress" is not necessarily a good thing, because you can get stuck in unfinished mode (like our book :().
2. You can publish a print-ready PDF (https://leanpub.com/productiongo/print) but you'll need to purchase an ISBN separately (if you want).For what it's worth, I found the printed copies of my self-published book from Amazon often had higher quality than many CS books I have from traditional publishers.
Can only recommend it to others after reading.