How to Write a Programming Book

This reminds me of when I just started high school and realized, "school is just a bunch of answers to questions nobody asked."

It's not that I didn't want to learn, nor even that I didn't want to learn those exact things -- just not have them fed to me at arbitrary intervals with total disregard for my actual state of mind.

(The original Dalton school mine was inspired by did this right, over 100 years ago, but most of the methods -- ie. letting kids learn what they actually care about, when it interests them most -- are illegal in my country.)

As for presenting the question first, at university this was often done, they would present us with some real world problem -- but then they would spoil the fun by instantly revealing the solution on the next slide! I like figuring things out, so in those moments I'd usually cover my ears and try to figure it out on my own.

Somebody else's solution only becomes interesting to me once I've invested the effort to make my own, and then I can compare and contrast.

>>It’s like, Chapter 1: Learning Your A,B,Cs. Chapter 2: >>Learning Your 1,2,3s. Chapter 3: Differential Calculus!

I hate this, but most authors do it. I recently bought a "beginner" book on Rust that promised to take things slow. And then suddenly, bam! There was dozens of lines of unexplained code, with the comment "This is easy to follow". No, it wasnt. I gave up on that book.

As someone who has written a few programming books, my experience is:

1. Explain every, yes, every single line of code. Whats so obvious to you isnt obivous to anyone else, unless they are Professor Charles Xavier and can read your mind.

2. Beginners get stuck in the most basic of things. In Python, my field, it is as simple as installing libraries. Even though I have many years expereince, sometimes just installing a library can leave me in tears.

I recently had an expereince of this from the other side(as a student)-- wanted to try out a Javascript library ,as I was following a tutorial. Ended up spending an hour configuring npm, fighting with different versions(as the library only worked with an old version of npm, and I had to figure out how to install multiple npm versions) , installing Python 2.7 (why the hell does a JS library need Python 2.7? Who knows?)

Ultimately, just gave it up. This is how beginners feel-- and I know from experience if you ask or complain about this, you will be attacked, asked to RTFM etc etc. "How hard can it be to install a library? Do a pip or npm install! Do your research before asking questions."

So beginners can get stuck and quit at the most basic of things. And beginner just doesnt mean someone new to programming -- I was the beginner when learning JS (and still am).

I generally just need that clue to go from beginner to intermediate, but no one usually provides those clues (and they might be different for everyone!)

The advice about assumptions we make about the reader's knowledge applies to much (most?) developer documentation too. The developer assumes the reader is an 'expert' at the same level as the developer. But too often the documentation provided is poorly written or incomplete. (Worst of all is when it simply doesn't exist.)

My suggestions for programming tutorials - whether they be in written form or video:

-- 1. Use graphics to illustrate programming constructs

Graphics are ideal for explaining programming language constructs rather than wordy text-only explanations. Visual explanations remain surprisingly rare. I realise many developers don't feel confident sketching, but illustrating a programming construct can easily be done with simple shapes or readily available graphics. It's the visual explanation of the programming construct that matters, not how aesthetically pleasing is the sketch or diagram. Drawing with a wobbly hand on paper or a whiteboard can be a completely effective method to explain a topic. In fact, likely more effective than just text-only.

-- 2. Seek inspiration from sources you would not consider (or consider beneath you) like tutorials for children

These Usborne 1980s computing and coding books for kids have been shared before on Hacker News. These are really well-written guides. They are more readable and enjoyable to read than many programming books published for adults today. Take a look and consider how clearly they are written.

Usborne 1980s Computer Books: https://usborne.com/gb/books/computer-and-coding-books

Or consider another source: BBC Bitesize - a educational resource for UK school kids. Look at this example of explaining programming constructs. So much more enjoyable than reading a wordy, dense textbook written for grown-ups (see the animated video): https://www.bbc.co.uk/bitesize/guides/zh66pbk/revision/2

-- 3. Use realistic examples, or examples the reader can relate to

This mirrors the advice in the article about using concrete examples. This is hard when using small examples to explain one idea at a time. However, using examples that the reader can relate to in real-life situations makes a difference to understanding.

Also, consider your audience as international. You may think calculating baseball scores is fun, but if half (or more) of your readers or viewers have no clue about baseball, you'll lose their attention or comprehension.

-- 4. Choose your metaphors carefully

So many tutorials on Object-Oriented Programming (OOP) start with: "objects in programming languages are like objects in real life". Is it time to rethink this cliched (and often misleading) metaphor?

-- 5. Finally, don't do this if you are making video tutorials on programming...

This is a parody video, but I'm sure everyone has encountered video tutorials like this. Why are so many programming tutorials still like this?

Every programming tutorial: https://www.youtube.com/watch?v=MAlSjtxy5ak

Meta-book-writing has entered chat.