
How to write a programming book - aqui_c
https://www.aquicarattino.com/blog/how-write-programming-book/
======
lmilcin
What pains me about programming books is that due to the market pressure the
balance is skewed extremely in the direction of beginner material and there is
precious little material for advanced users.

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.

~~~
dkersten
Another thing that bothers me is that most intermediary books on a topic tend
to start with a good chunk of beginner stuff. For example, many game
programming books will cover a ton of beginner material at the start, same
with graphics books or books on a particular programming language. I shudder
to think of how much duplicated content that I will never read because I'm no
longer a beginner is sitting in my bookshelf. If I buy an intermediary or
advanced book, I don't need a recap giving me the absolute basics! Eg if its
an intermediate-level programming language book, don't tell me how to do
simple conditionals or loops or something that I definitely already know to
consider an intermediate-level book...

~~~
reificator
This is why I look for gems like Professional Javascript for Web
Developers[0][1]. _(I can 't speak to the latest version, I think I read the
3rd edition from 2012.)_

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+...](https://www.wiley.com/en-
us/Professional+JavaScript+for+Web+Developers%2C+4th+Edition-p-9781119366577)

[1]: [https://www.amazon.com/Professional-JavaScript-Developers-
Ma...](https://www.amazon.com/Professional-JavaScript-Developers-Matt-Frisbie-
ebook/dp/B07YP276S1/)

~~~
travisjungroth
Fluent Python sounds like the same thing. It assumes experience in another
language and having done the official Python tutorial.

~~~
reificator
Thanks, I'll have to check it out. I've definitely dabbled in Python but I
would like to learn it properly.

------
billme
Generally speaking, books as a format make no sense. I have seen the financial
records for number of popular tech book authors — and numbers related to them
having published, for example: products, services, consulting & speaker fees,
etc. If the author is trying, they make way more money from the numbers
related to them publishing than the book sales.

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.

~~~
munificent
_> Generally speaking, books as a format make no sense. _

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.

~~~
billme
>> “conventional tech publishers make no sense economically” [...] “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.)

~~~
munificent
Yes, me.

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.

~~~
billme
First, congratulations, thanks for publishing, thanks for sharing your
experience!

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](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.

~~~
munificent
All of that is true, but it's also worth balancing that with the fact that
when I was writing that book, I was only spending about an hour a day on it,
and now I spend zero hours a day. The long tail of passive income seems to be
pretty long so far.

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.

------
Syzygies
This is relevant to me because I'll likely be teaching Linear Algebra online
in the Fall. I'm rethinking support materials from scratch. This article does
not rethink its genre from scratch. And I nearly stopped reading, unwilling to
take advice from a fixed pitch body font.

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.

~~~
ivan_ah
Good luck with the LA book. It is a beautiful subject with so many
applications, so a great opportunity to do an original take on it.

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...](https://minireference.com/static/excerpts/noBSguide2LA_preview.pdf)

[2]
[https://minireference.com/static/tutorials/linear_algebra_in...](https://minireference.com/static/tutorials/linear_algebra_in_4_pages.pdf)

[3] [https://github.com/minireference/noBSLAnotebooks#no-
bullshit...](https://github.com/minireference/noBSLAnotebooks#no-bullshit-
guide-to-linear-algebra-notebooks)

[4]
[https://minireference.com/static/tutorials/conceptmap.pdf](https://minireference.com/static/tutorials/conceptmap.pdf)

------
Vaslo
One thing that is constantly left out of books is challenging problems with
solutions for the user to cement the new ideas they’ve learned in actual
examples. It’s very easy to read along and nod your head but it’s very hard
(at least for me) to incorporate my new skills without memorable hands on
examples.

~~~
TrinaryWorksToo
As a reader, what I do is make up my own challenges. Do I feel comfortable
modifying the code and knowing it will still run error-free?

~~~
onemoresoop
I do the same when learning a new concept, find a little way to apply it by
slightly to heavy modifying the original code until it clicks. I save those to
a folder I can reference sometime in the future. I’ve been doing this for a
really long time and it works well for me.

------
KineticLensman
I think the article is really general advice about (tech) writing, not about
writing a programming book. There is very little if anything specific to
programming itself, e.g. e.g. the types of code fragments you should use as
examples.

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.

~~~
ghaff
>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.

~~~
TheOtherHobbes
This is a much more useful comment than the OP.

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.

------
csours
> "If you ever start the path of writing a book, you should ask yourself why
> you are doing it."

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.

~~~
sitkack
Start with a round table, provide a space so that people open up about what
they find confusing, try to map out the knowledge gaps.

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?

~~~
csours
It's about IT for Mfg, so kind of broad. Sorry about the spark plugs.
Packaging is a bitch.

------
sideshowb
"...in 24 hours"

------
throwaway_pdp09
This would be interesting if I could read it. Would it be possible to display
text without enabling JS?

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.

~~~
aqui_c
I'm working on that. I just used a stock template for the website.

~~~
carapace
Cheers! Much appreciated. :-)

