I wrote a couple of books recently and have some tips for aspiring authors:
* 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.
I followed a similar path with Computer Graphics from Scratch [0], somewhat accidentally. You'd be surprised about how much valuable feedback a publisher can give on such a technical topic! When No Starch Press approached me I thought "the content is almost finished, this will take a month or two". It took two years, and the book is significantly better after I went through the process with them.
Thanks for sharing! I actually chatted with No Starch Press and met with them in their offices. Really nice people and amazing vibe. I am working on a PySpark book and will reach out to No Starch again based on your comment.
Two years would cause most technical books to miss a market window. Other will have written on the topic, and perhaps be established as a standard by then.
It’s great that the book is improved, but that delay is a killer.
Good point. To be fair, most of the delay was my own fault, due to life events (moving internationally, starting a new job, the f*** pandemic, etc). I was the bottleneck, not them.
100% agree with this sentiment. My co-author and I are wrapping up a book with No Starch and the experience has been very positive. The editing, in particular, has been stellar.
> I felt confident I didn't need a professional editor.
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.
Well from a purely monetary standpoint, if you make 4x more money when publishing yourself you can afford to sell 4 times fewer books to make the same amount, so the real question is: can the editor impact my book so much that it will increase sales 4 times?
Not saying that you are wrong, more that there are legitimate reasons why an editor might not be the right way forward.
> more that there are legitimate reasons why and 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.
Also what is the cost of hiring an editor if you are self publishing? That’s another route and I bet you could find a good one at a more reasonable cost.
For fiction editing (developmental and copy) I've spent around 550-700 USD for 80k words. Not sure how that converts for a programming book but the editing was well done and really improved the manuscript which resulted in a big increase in sales for follow up books.
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.
> Target middle school reading level. Short sentences & simple words. Technical audiences want information and don't care much about literary prose.
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:
If your material has a long life, you could self publish. Then a year or 2 later after sales have dwindled you could look for a publisher interested in taking over it & giving it a new life.
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.
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!
The point about Credibility is interesting. There's something about someone who's written a technical book that automatically seems impressive just because writing a book is hard, and it's easy to assume that the person knows a lot. A long time ago I used to do technical review for a publisher on books about code. It was pretty obvious that some authors didn't really know what they were talking about. They knew enough to write something, but there were always a lot of mistakes.
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.
It was pretty obvious that some authors didn't really know what they were talking about. They knew enough to write something, but there were always a lot of mistakes.
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.
for a technical work, you would hope the publisher assigned some people to check the work
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.
I did technical reviewing for a while. What frustrated me most was when I would say, "this isn't right, it's more nuanced than that" and they would come back and say, "this is a book for beginners so we'll just leave it the way it is".
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".
I had this experience, too, after tech reviewing quite a few books. I quickly got to the point where I didn't want to even look at the final product, because of all the pointed-out flaws that would still remain, and I'd know the book could have been so much better, except that some editor was in a rush, or lazy.
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.
I like the idea that all the code in the book goes through a CI so any edited get compiled and unit tested. Certain words and phrases could be given “type annotations” to check consistent use of language.
Not to replace human review but should catch a lot of mistakes
>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.
I once was contacted by a technical book publisher, known for producing a lot of so-so books on specific topics, to be a reviewer for a book on then-hot technology. The book was technically OK, but was put together in such a disorganized and sloppy way that it was a hard slog to look through it. As a reference text, it would have been ok had it been organized as such. This was before stackoverflow, but you could make the same book today by scraping all the stackoverflow questions and answers on a topic, throwing them together and calling it a day.
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.
I have published three books (with a publisher), and I can confirm that Credibility was one of the bigger motivations both for writing them, and for going with an established publisher.
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 technical book publishing, the publisher is a good signal as to the quality of the contents inside. I have never seen a worthwhile book from APress.
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.
> Now if you send in a paper that has a radically new idea, there's no chance in hell it will get accepted, because it's going to get some junior reviewer who doesn't understand it. Or it’s going to get a senior reviewer who's trying to review too many papers and doesn't understand it first time round and assumes it must be nonsense. Anything that makes the brain hurt is not going to get accepted. And I think that's really bad.
-- 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.
Why would anyone consider an entry level title as a sign of credibility at this point? I remember picking up such books a quarter century ago where it was abundantly clear the author either had very little knowledge on the subject or the publisher was simply trying to profit off of the latest fad. That isn't to say that a book cannot be used as proof of knowledge, communications skills, etc.. In some ways it may be better than most forms of proof since it can actually be verified. On the other hand, it's useless unless the quality is actually assessed.
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.
Sounds similar to Allen Downey's "Textbook manifesto" (https://greenteapress.com/wp/textbook-manifesto/). The manifesto can be summed up in a single sentence: "Students should read and understand textbooks." :)
Have you tried filtering your choice of books through something like Goodreads? In my experience choosing books with a minimal rating of at least 4.0, preferably >4.2 really leaves you with the cream of the crop. I just got deep into systems and software architecture and I've been very impressed with the first three books I've read. (Haven't tried it on actual programming books, but I'm pretty sure the outcome would be the same).
I think one piece of advise missing here is: define your value add upfront. There are 1000 books on Go out there. What are you bringing to the table that others don’t?
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.
While the tone of the parent is a bit, well, it could be better :) I do think the parent has a point. For example, I just finished reading Modern Operating Systems by Tanenbaum. His experience shows. This form of experience cannot be showcased by someone who's learning or just has learned a particular technology. And I know I'm taking one of the giants as an example, and they show this particular example in its most extreme form.
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.
I agree. That said, I think the "your grandma" line should be retired.
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.
> I agree. That said, I think the "your grandma" line should be retired.
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.
Off topic, but as the father to a seven year old I’ve discovered how many things I don’t really understand over the last few years. His interest in black holes recently has me thinking I need to read a whole heap about relativity.
ِ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.
Not to mention that the demographic of "grandparents whose grandchildren are old enough to explain computer issues to them" had mainstream access to computers much earlier in their lives than the same demographic ~20 years ago when access to computers hit its inflection point between "enthusiasts" and "everybody".
I'm finishing up my LaTeX book which has its origins from teaching LaTeX classes for the TeX Users Group in the 90s. That teaching experience is essential for the quality of what I have because I have the experience of knowing what's helpful for LaTeX beginners and what's needlessly confusing. I do suspect that my original target audience—math department secretaries—is no longer the target audience.
Certainly agree, you forget all that you have learned and even harder to recall are those epiphany moments that altered your point of view entirely. If you can recreate those moments for others, you add an edge to your teaching.
I loathe this saying, along with the entire "explain it like I'm five" trend that has taken off in recent years. Yes simple and concise explanations are valuable, but there still needs to be a baseline. There are certain things that just cannot be explained to a layperson unless they have some prerequisite knowledge in the field. I didn't know Einsten's grandma, but it is safe to assume that the lady did not exactly grasp the theory of relativity or quantum physics.
Here's a better quote (also sometimes attributed/misattributed to Einstein) – “Everything should be made as simple as possible, but no simpler.”
I agree that you could technically say the table of contents is an index (comparing it to a DB index), but because "index" also means something completely different in this context I would avoid using the term this way.
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!
Self-publishing has always been an option for authors. Some publishing houses offer you resources to publish your work. You simply pay them and they review and print your book. It seems to be a fair arrangement. However, after five minutes in Google, you will find out that many self-published authors had terrible experiences or were scammed. Finding a decent and professional publishing house requires time. You cannot trust the first one you find in Google.
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).
The author forgot to mention that Amazon kindle publishing take 70% out of your sale price :) Also, that when they print the books, the quality sucks - thick cheap printer paper, toner saver enabled. As a customer I have had very bad experience with books printed by Amazon.
> Also, that when they print the books, the quality sucks - thick cheap printer paper, toner saver enabled.
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.
* 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.