How to write a programming book
aquicarattino.com
aquicarattino.com
If you look at other branches of knowledge, say electronics, there is couple of books for beginners and then massive selection of highly specialized books for experts.
I get that part of this is due to multitude of languages, paradigms, frameworks, etc. but I suspect that a huge part is due to the fact that programming book writers have huge incentive to make the book palatable to absolute beginners and anything else seems to be a sure way for the project to tank.
The problem is that this is still a crazy fast growing field. Say we double in number every 5 to 10 years. That means at 5 years experience you are more experienced than half the industry.
That’s mindboggling.
Newbies also need more help and are more willing to pay for help.
Oldbies only pay for help when entering a new area. Like a fortran engineer picking up React or a JS person getting into C++
One problem is that software engineering doesn’t quite value experience yet. Easier to throw 3 newbies at a problem than 1 senior who’s never seen this new tech anyway.
The other issue is that engineers are smart and motivated by problem solving. They’d rather figure it out themselves than take all the fun out by just learning it like a normal person and reaping the rewards.
Also advanced stuff often gets so in the weeds that only you and 50 of your friends in the whole world even care. Or it’s so specific to your company tht only other people at your company care.
I personally wouldn't wanting to be competing with all the other beginner material and sufficiently advanced material would take forever to produce.
But if there was a 100 page book on writing an Elixir/Phoenix app and deploying it on K8s across 4 cloud providers, using a CDN and Aerospike, I'd pay 50$ for that.
That’s the other problem. The thing you just described is worth 6-figures when sold as a consulting deal. Why do you expect to pay just $50 for the book version?
https://www.michael-noll.com/projects/
Does a very good job in this regard. I think if you have a consulting agency where you can train or lead on multiple projects, then a book could be a very good sales vehicle.
It's a book about Javascript that assumes you've written software in other languages before. I believe the book uses Java/C#, Python, and maybe a couple other languages as reference points.
It describes language behavior and constructs that may be new to you, and details where the familiar may differ from what you'd expect. For instance, the section on `var` and how function scoping (and hoisting) differ from block scoping was quite detailed, but I don't remember it spending a lot of time on what it meant to declare a variable or why scoping rules matter.
If the book had a beginner focus I might have seen the section on declaring variables, skimmed to see the `var` keyword, and skipped the rest. Then I'd have written a bunch of code that would bite me later, because why would you ever assume function scoping when coming from another language?
It's unfortunate that it's so difficult to find books with either an intermediate to advanced focus, or a focus on switching languages, as I think both are sorely needed in the current programming ecosystem.
[0]: https://www.wiley.com/en-us/Professional+JavaScript+for+Web+...
[1]: https://www.amazon.com/Professional-JavaScript-Developers-Ma...
Much credit goes to the author of previous editions, Nicholas Zakas, for dictating the style. He offered this advice when I began the new edition:
I tried to make it a book that had a distinctive approach, which is that it didn't treat the reader with kid gloves and went deep into technical details to people could really understand the language. This, more than anything else, is what people have told me they enjoyed about the book. It was unapologetically not for beginners.
More than anything else, this advice is what guided me in preserving the original style in the new edition.
That's pretty good customer service, but it's not something you can get with a book. I suspect "intermediate" books with a "beginner" start are attempting to address this problem and head off the terrible reviews. Perhaps it's an ego thing with software engineers. "I'm no idiot, so I'm intermediate," "I've been doing software for decades so I'm advanced," and not realizing that it's about your experience with this technology, not your brain.
That just doesn't make any sense.
Obviously, the author of the book can explain the book is really meant for a user with some prior knowledge and experience of the matter. If the reader ignores it it's not really a problem of the author to deal with.
My background is mathematics and, as an example, just recently wanted to pick up some control theory. It is absolutely normal I pick up a book I have not enough knowledge to even start reading. It is normal. You get something else, study it, then go back to the one you tried to understand.
“Oh!!! That’s what they meant here!!!”
I say this once a month with something I’ve read 50 times. We need to reward people for having determination, not make every single book beginner friendly at the expense of deep material. We’re doing the world a huge disservice by limiting the potential of what people could be sharing.
The style we use to teach is optimized for speed of learning and teaches this way using the 'constructivist' method. I expand on this learning style, and why it is so effective more in this post: https://fromtoschool.com/why-most-programming-tutorials-are-....
But if interested you can leave your email address on the form at the bottom of the post.
A lot of research papers can be found online for free. What problem are you trying to solve that you feel would be helped by advanced material not found in research papers and/or computer science textbooks?
For me, the problems I've encountered that I thought were problems of lack of advanced learning material, have turned out to be problems of absence of tooling, libraries, frameworks and the will to create them.
In my particular case - I became an iOS developer and found out we're still paying people 100k+ to manually create trivial phone apps that fetch trivial database queries via json and display them in rather trivial ways on screens.
You wouldn't believe the number of people working on any given banking app that lets you display your past transactions and transfer money in-between accounts - it's basically a folder/file viewer with pre-defined file types and a couple of pre-defined actions for each. We've had folders, files and transactions to ensure correctness for decades! People are still re-creating these features!
Why do we have separate banking apps that do the exact same thing and why does displaying text fetched from a database and letting you modify it in the most trivial way, a job that pays 100k+ while producing bug ridden code?
There is no book to solve this problem and I believe most of the people employed in software development are churning out or maintaining this type of code. As a result, the market for advanced techniques in computer science is incredibly tiny - if you removed the idiotic whiteboard waterboarding techniques, academia and R&D at big corporations, you'd find out that there is maybe a few thousand people world-wide who are genuinely interested in putting advanced computer science to use.
I'd say this hypothesis explains why we don't have any actual progress in the field, just more javascript frameworks (simplifying, of course ) :) It doesn't explain very well what those billions of dollars in R&D at big corps are accomplishing besides removing ports from laptops and coming up with new keyboard mechanisms that fail when dust falls on them (lol) - maybe we're one day away from a quantum computer that changes everything? I have my doubts :)
Nah, there are lots of people writing big complex programs with big complex architecture. Architecting programs isn't an "advanced compsci topic", but there are lots and lots of books that don't really talk much about it. Instead they show you how to use your programming language's (or framerwork's, database's, etc.) primitives in a basic way. That's pretty much the things you could just look up in a reference manual. Then you figure out the hard stuff yourself.
They tell me how to hold this bundle of hammer and nails, but I need to figure out how to design a skyscraper with them..
To me it reads like "now that you know how to hold this clumsy 90s OOP hammer, here's how to swing it". That's a far cry from architecting systems, and not a particularly motivating read for someone who's really not into that flavor of OOP (or much OOP at all).
There are a lot of experts who have profoundly deep skills, but don't happen to write in your personally preferred writing style. Do you want that to get in the way of you learning from them? If not, you gotta meet them halfway.
I've learned a lot from well-written books. I've also learned a lot from frankly poorly-written books. Mastery takes work.
Time and time again I read things only to regret it later because I didn't get my time's worth out of it and probably could've spent that time on something more useful.
It's less a question of style and more a question of content. Do I feel like I'm learning something insightful or important? If not, I start to get bored. If it's a book people recommend a lot, I force myself to keep reading, and tend to get more and more bored. I might or might finish, but in the end I usually regret it. It's very rare for a book that doesn't start out well to do a U-turn and get good towards the end.
A classic problem, and the reason that some questionable authors with unreliable content are nevertheless among the most popular in their field, is that the student of a technical subject is by definition never going to be qualified to evaluate tutorial material aimed at their current level. We all rely on the opinions of those more skilled or experienced than ourselves to guide us, at least until we reach a level where there are no more tutorials and instead we're learning from our own experiences including original research and discussions with peers.
In the case of Design Patterns specifically, if you're not into the kind of OOP where those patterns apply then it will have much less value to you. However, I'd say anyone who is working in a language like Java, C++ or C# should have at least passing familiarity with the patterns within and their names, if only to recognise the concepts and key details when they come up in discussion with fellow developers or get mentioned in code or documentation. Some of the ideas behind those patterns are relevant in non-OOP contexts as well, but in other programming styles they are often expressed very differently, which is why I say the book would have much less (but not necessarily zero) value to someone whose interests lie away from class-based OOP.
If you like writing long form tech guides, do yourself and your audience a favor, figure out how to publish your materials for free digitally and grow an audience you have direct one-on-one access to, then allow people to order paper versions if that’s what they prefer.
Then, writing a book becomes easy: grow audience, provide an outline, get feedback, write more, write testable code, get more feedback, etc.
Anything you write (as in subsection) should have a timestamp of when it was: written, rewritten, last reviewed, test, environment tested, etc.
That said, you would need to have a quantifiable definition of done and likely be a good idea to account for absolute failure in case something comes up an “done” is never accomplished. Until it is “done” likely be good idea to escrow the funds, but then you run into issue like paying taxes, transaction fees, etc.
- estimate of reading time - level of knowledge - way to link deeper content
This is such a silly assertion. Books have been one of the most effective ways for an informed author to get large, complex topics and rich experiences into a another persons head literally since the Roman Empire.
Even in today's world where we have an infinite number of other formats and media to choose from, millions of people still prefer and learn from books. The ability to encode spoken language into a series of written words that can be consumed at a pace the reader controls is one of the most powerful technologies humans have ever invented. And an author taking the time to organize an entire body of work into a single coherent linear narrative is one of the most effective tools to move information across brains.
> I have seen the financial records for number of popular tech book authors
I think what you're trying to say is that conventional tech publishers make no sense economically, and I am inclined to agree with that. The idea that an author can do 90% of the work and get 10% of the royalties is just bananas to me. That kind of royalty sharing only made sense in a time when publishers formed a hermetically sealed cartel preventing independent authors from easily accessing bookshelves. Those days are thankfully over.
It is possible to make decent money from writing technical books if you self publish and build an audience yourself.
Do you have an example of an author doing this? (Meaning all they do is self-publish books and have disclosed financials.)
My self-published book "Game Programming Patterns" has made me a lot more money every year for the past six years than I ever expected. It's not enough to live off of, at least not in an expensive city while raising a family, but it's nothing to scoff at either. I could probably make quite a bit more if I put time into marketing, supplementary materials, etc. As it is now, I just let the checks from Amazon etc. roll in and treat it as a nice bonus to my day job income.
If I lived somewhere cheaper, wrote full time, and made some adjustments in my lifestyle, I could probably get by on just my writing.
Second, yes, maybe I was not clear, my advice relates to the average author on a simple straightforward method of write a book that reduces the odds of it not being of use of the audience it seeks.
Lastly, might be wrong, but it appears:
(A) at least on Amazon, your book appears to be rank in the top 20,000 of all books;
(B) you appear to have published a singular book;
(C) as you say, yourself, it does not make enough for someone to live in a major city;
(D) writing books is not your primary means of income;
—- to me, what I hearing does not conflict at all with my analysis and your example, to me is survivor bias: https://en.m.wikipedia.org/wiki/Survivorship_bias
——
Writing multiple best selling books year after year is VERY hard to do as a means of income. There are much easier ways to earn an income and share what you know. If someone wants to do that, awesome, though I do not have advice for doing that, nor do I know of anyone else that does; that would result in publishing 1+ successful books a year. My advice is just no nonsense take on being reducing odds of book being useful, which for the average author is much more of a challenge.
You're right that it will be hard for many people to make a living solely off writing technical books. But I also think it's true that you can make more money that most people realize just by not giving a traditional publisher a huge cut of it. Maybe not enough to live on, but likely enough to make it worth your while.
I've learned dozens of programming languages, and I find programming books increasingly unreadable. They all give me that feeling of ADHD that actual programming heals.
I've also made progress learning various human languages. No single approach works. Doing crosswords in old age doesn't fight off dementia but does make one better at doing crosswords. For language aquisition, read with the sole goal of getting better at reading. Listen with the sole goal of getting better at listening. Repeat phrases in the car as if that's a self-contained game one plays. Then trust that these separate skills will integrate as one travels; they do.
For anyone who has learned the board game of Go, it's interesting how books on Go are compartmentalized. There are books solely dedicated to short timescale tactics, for example.
After a few programming languages, one can easily absorb the "short timescale tactics" of a programming language, and still be at a loss on idiomatic ways to assemble complete programs. Just as the best mathematicans only read original literature, the best programmers simply read code. A programming book can ease the transition to reading code. We should be clear that this is our primary goal.
One experiences a more intense sensation of comprehension, reading and understanding how a short complete program works, than reading any neverending text that ambles on. Take a cue from human language aquisition: Programming books should deliver a sequence of "aha!" moments of comprehension, teaching language constructs through explanations of a sequence of cleanly separated short complete programs. Their success should be measured in terms of the enjoyability and intensity of the experience of reading code this way. Leave it to the reader to find other ways to put together the rest.
In case this is might be helpful, here is a preview of the LA book I wrote[1] and the condensed four-page-in-small-font tutorial version[2]. You might also consider using a computer algebra system for teaching, see [3] for my take on LA using SymPy. Last but not least, I highly recommend the CMapTools software for creating concept maps, which can really summarize the field in a very compact form[4].
[1] https://minireference.com/static/excerpts/noBSguide2LA_previ...
[2] https://minireference.com/static/tutorials/linear_algebra_in...
[3] https://github.com/minireference/noBSLAnotebooks#no-bullshit...
[4] https://minireference.com/static/tutorials/conceptmap.pdf
Apologies, I really tried to make this not sound condescending!
Also, apart from the line:
> You can always ask feedback from people you trust to gain confidence
there is no mention of getting someone to proofread or even copy edit the book. This would also seem really important for a programming book - e.g. to check that the examples work away from the author's dev environment.
You're actually talking two different things.
Someone needs to proofread/copyedit the book. Full stop. And, unless you have a partner or particularly close friend who will/can do a careful edit for you for a case of beer and a pizza, you're going to have to pay someone.
For a programming book (or other types of technical books), you probably need a technical reviewer. If it's just a sanity check for technical accuracy, colleagues etc. can probably do that. But to work through all the code in a book, again, someone will probably have to get paid.
Books need review - not just a few comments on the general concept, but line by line proofreading of the English, and fact checking of every single technical statement.
This is fundamental to the process. It's not an aspiration, it's part of the writing process - because often you'll be writing content while other content is being reviewed, and feedback from both can influence the rest.
All what you mention as missing, is part of my current ongoing process, and I still haven't learned nor tested enough as to summarize it.
I hope the process goes well! Doing what you are doing is really difficult and I have lots of respect for those who try!
I've wanted to create a short video series for my workplace, but I'm stuck on what the approach and theme should be.
The series would be about automotive assembly, and I have a lot of things to talk about, but I keep getting stuck on what people would be interested in and what would be helpful.
Is this about design for manufacturing from an assembly standpoint? Would it also cover repair? The spark plugs on a VR6 are inaccessible, can you fix that?
I have read several IT books recently and they aren't good. Basic stuff like visibility of diagrams, presenting advanced subject matter but also supposedly in a way that will teach you programming, or having pages of code to illustrate something trivial.
No, because then how would it set up pullquotes like "If you don't set a baseline somewhere, you risk starting a book that grows backward" that you can tweet at the push of a button? (Is that really a thing? I guess it must be somewhere, but it's new to me on a (I guess) programmer's blog.)
Stopped doing it as I got negative feedback about it being annoying. I never tracked how many tweets I get out of it though. So if you aim for popularity (unlike me) it might still be worth it.
It was one of the big reasons I used RestructuredText as markup language for my static website generator. It is extensible enough to make these tweet-blocks with just:
.. tweetable :: Psychological Safety is THE core factor for Great Teams says Google