How to Write a Programming Book(cscalfani.medium.com)
cscalfani.medium.com
How to Write a Programming Book
https://cscalfani.medium.com/how-to-write-a-programming-book-76ab4f8a7071
10 comments
A bit off topic: Over many years of college and grad school, the one course that gave me the solutions to too many problems I didn't have was my first class on differential equations.
I think one of my favorite professors, Gian-Carlo Rota summed it up best in a short essay, Ten Lessons I Wish I Had Learned Before I Started Teaching Differential Equations, see [1]. It's hilarious and just like him.
I remember the first lecture of his I attended on probability. Wearing his trademark three piece brown suit and red tie at the front of the lecture hall and standing to one side of the stage, he said "I feel a draft, is a window open?". After a bit of looking around, we all reassured him that the windows were closed, he said "Well, I feel a breeze; yes definitely there is a breeze on my brow." Just then he looks up at the wall and does a double take as he notices he is standing under an air conditioning vent. He was whimsical, funny, and absolutely brilliant.
For anyone that has had to take the first semester of differential equations check out his essay.
[1] https://web.williams.edu/Mathematics/lg5/Rota.pdf
I think one of my favorite professors, Gian-Carlo Rota summed it up best in a short essay, Ten Lessons I Wish I Had Learned Before I Started Teaching Differential Equations, see [1]. It's hilarious and just like him.
I remember the first lecture of his I attended on probability. Wearing his trademark three piece brown suit and red tie at the front of the lecture hall and standing to one side of the stage, he said "I feel a draft, is a window open?". After a bit of looking around, we all reassured him that the windows were closed, he said "Well, I feel a breeze; yes definitely there is a breeze on my brow." Just then he looks up at the wall and does a double take as he notices he is standing under an air conditioning vent. He was whimsical, funny, and absolutely brilliant.
For anyone that has had to take the first semester of differential equations check out his essay.
[1] https://web.williams.edu/Mathematics/lg5/Rota.pdf
good article.
>>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).
>>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 remember being confounded by the absence of a return statement in rust functions for a few days. I only understood that a statement without a semi colon is returned.
When writing a tech book, follow the Zen of Python. Explicit is better than implicit.
When writing a tech book, follow the Zen of Python. Explicit is better than implicit.
A really nice article. I am a teacher now, too, and I would add this to his notion of giving a problem before a solution. I teach English, and I have learned that giving students definitions to every word I am going to use is not as beneficial is giving them the sense of what I am trying to say and letting their minds figure out the meaning. This is obviously more frustrating for some students, but when you understand the general meaning of a something you hear, I really believe your mind starts to work a lot harder than if you are spoon fed things, which is a lot more beneficial to learning in the long run.
Since surviving my Physics degree in the 90s, I wanted to be an educator and write books that filled in the gaps between beginner and expert -- the problem was becoming an expert and understanding the essence of things in that gap.
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!)
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!)
A good article with lots of thoughtful insights in how to write a programming book.
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
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
Thousands of words on how to write a programming book, without having to actually write a programming book, and not one single example of a good book or a bad book.
Meta-book-writing has entered chat.
Meta-book-writing has entered chat.
Huh?? The book he wrote is literally linked in the first paragraph
a) I'm referring to his diatribe about bad books. Now we will see articles about how books should be written. The entire article is a about why he wrote the book. That's what I meant about "meta...".
b) Citations. Making claims about how awful coding books are without examples is a bit thin, IMHO.
b) Citations. Making claims about how awful coding books are without examples is a bit thin, IMHO.
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.