[HN Gopher] How to Write a Programming Book
___________________________________________________________________
How to Write a Programming Book
Author : schot
Score : 90 points
Date : 2021-06-17 09:13 UTC (13 hours ago)
(HTM) web link (cscalfani.medium.com)
(TXT) w3m dump (cscalfani.medium.com)
| jkmcf wrote:
| 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!)
| andai wrote:
| _3. Never give a student a solution to a problem they don't
| have._
|
| 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.
| SavantIdiot wrote:
| 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.
| softblush wrote:
| Huh?? The book he wrote is literally linked in the first
| paragraph
| SavantIdiot wrote:
| 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.
| shantnutiwari wrote:
| 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).
| magpi3 wrote:
| 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.
| open-source-ux wrote:
| 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
___________________________________________________________________
(page generated 2021-06-17 23:02 UTC)