TE
TechEcho
Home24h TopNewestBestAskShowJobs
GitHubTwitter
Home

TechEcho

A tech news platform built with Next.js, providing global tech news and discussions.

GitHubTwitter

Home

HomeNewestBestAskShowJobs

Resources

HackerNews APIOriginal HackerNewsNext.js

© 2025 TechEcho. All rights reserved.

How to Write a Programming Book

106 pointsby schotalmost 4 years ago

6 comments

andaialmost 4 years ago
<i>3. Never give a student a solution to a problem they don’t have.</i><p>This reminds me of when I just started high school and realized, &quot;school is just a bunch of answers to questions nobody asked.&quot;<p>It&#x27;s not that I didn&#x27;t want to learn, nor even that I didn&#x27;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.<p>(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.)<p>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&#x27;d usually cover my ears and try to figure it out on my own.<p>Somebody else&#x27;s solution only becomes interesting to me once I&#x27;ve invested the effort to make my own, and then I can compare and contrast.
评论 #27551339 未加载
shantnutiwarialmost 4 years ago
good article.<p>&gt;&gt;It’s like, Chapter 1: Learning Your A,B,Cs. Chapter 2: &gt;&gt;Learning Your 1,2,3s. Chapter 3: Differential Calculus!<p>I hate this, but most authors do it. I recently bought a &quot;beginner&quot; book on Rust that promised to take things slow. And then suddenly, bam! There was dozens of lines of unexplained code, with the comment &quot;This is easy to follow&quot;. No, it wasnt. I gave up on that book.<p>As someone who has written a few programming books, my experience is:<p>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.<p>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.<p>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?)<p>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. &quot;How hard can it be to install a library? Do a pip or npm install! Do your research before asking questions.&quot;<p>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).
评论 #27547037 未加载
magpi3almost 4 years ago
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.
jkmcfalmost 4 years ago
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.<p>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!)
open-source-uxalmost 4 years ago
A good article with lots of thoughtful insights in how to write a programming book.<p>The advice about assumptions we make about the reader&#x27;s knowledge applies to much (most?) developer documentation too. The developer assumes the reader is an &#x27;expert&#x27; 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&#x27;t exist.)<p>My suggestions for programming tutorials - whether they be in written form or video:<p>-- <i>1. Use graphics to illustrate programming constructs</i><p>Graphics are <i>ideal</i> for explaining programming language constructs rather than wordy text-only explanations. Visual explanations remain surprisingly rare. I realise many developers don&#x27;t feel confident sketching, but illustrating a programming construct can easily be done with simple shapes or readily available graphics. It&#x27;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.<p>-- <i>2. Seek inspiration from sources you would not consider (or consider beneath you) like tutorials for children</i><p>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.<p>Usborne 1980s Computer Books: <a href="https:&#x2F;&#x2F;usborne.com&#x2F;gb&#x2F;books&#x2F;computer-and-coding-books" rel="nofollow">https:&#x2F;&#x2F;usborne.com&#x2F;gb&#x2F;books&#x2F;computer-and-coding-books</a><p>Or consider another source: <i>BBC Bitesize</i> - 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): <a href="https:&#x2F;&#x2F;www.bbc.co.uk&#x2F;bitesize&#x2F;guides&#x2F;zh66pbk&#x2F;revision&#x2F;2" rel="nofollow">https:&#x2F;&#x2F;www.bbc.co.uk&#x2F;bitesize&#x2F;guides&#x2F;zh66pbk&#x2F;revision&#x2F;2</a><p>-- <i>3. Use realistic examples, or examples the reader can relate to</i><p>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.<p>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&#x27;ll lose their attention or comprehension.<p>-- <i>4. Choose your metaphors carefully</i><p>So many tutorials on Object-Oriented Programming (OOP) start with: &quot;objects in programming languages are like objects in real life&quot;. Is it time to rethink this cliched (and often misleading) metaphor?<p>-- <i>5. Finally, don&#x27;t do this if you are making video tutorials on programming...</i><p>This is a parody video, but I&#x27;m sure everyone has encountered video tutorials like this. Why are so many programming tutorials still like this?<p>Every programming tutorial: <a href="https:&#x2F;&#x2F;www.youtube.com&#x2F;watch?v=MAlSjtxy5ak" rel="nofollow">https:&#x2F;&#x2F;www.youtube.com&#x2F;watch?v=MAlSjtxy5ak</a>
SavantIdiotalmost 4 years ago
Thousands of words on how to write a programming book, without having to actually write a programming book, and not <i>one single example</i> of a good book or a bad book.<p>Meta-book-writing has entered chat.
评论 #27542008 未加载