10 ms·

How to write a programming book

166 points by aqui_c 6y ago

throwaway_pdp09 6y ago
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.
- JadeNB 6y ago
  > Would it be possible to display text without enabling JS? No, because then how would it set up pullquotes like "If you don't set a baseline somewhere, you risk starting a book that grows backward" that you can tweet at the push of a button? (Is that really a thing? I guess it must be somewhere, but it's new to me on a (I guess) programmer's blog.)
  - chrisa 6y ago
    You can't actually send a tweet at the push of a button (unless you're connected with twitter oauth with the right permissions), but what you can do (and that button does) is opens the tweet composer pre-filled with the quote, ready for you to then just hit "Tweet"
    - qznc 6y ago
      I used to do that on my blog. Example: http://beza1e1.tuxen.de/team_building.html http://beza1e1.tuxen.de/team_building.html Stopped doing it as I got negative feedback about it being annoying. I never tracked how many tweets I get out of it though. So if you aim for popularity (unlike me) it might still be worth it. It was one of the big reasons I used RestructuredText as markup language for my static website generator. It is extensible enough to make these tweet-blocks with just: .. tweetable :: Psychological Safety is THE core factor for Great Teams says Google
  - aqui_c 6y ago
    They are just links to Twitter, no JS involved on those fragments.
- dorkwood 6y ago
  Someone needs to make a Hacker News bingo card. "Doesn't work with JS disabled" would definitely be on there.
  - throwaway_pdp09 6y ago
    Along with "you need JS for the modern web"
    - clarry 6y ago
      "it's just text and images"
- aqui_c 6y ago
  I'm working on that. I just used a stock template for the website.
  - carapace 6y ago
    Cheers! Much appreciated. :-)
  - dkersten 6y ago
    The low contrast text is also really hard to read.
- carapace 6y ago
  Yeah, I'm getting pretty sick of sites that want to run JS to show static content.
Vaslo 6y ago
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 6y ago
  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 6y ago
    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.
- yesenadam 6y ago
  Gee, write a program using what you just learnt and see if it works. You want someone to tell you what program to write?! I assume it's a book for kids, or a school textbook, when I see exercises like that. I don't understand the demand that books not only tell you things, but tell you how to learn everything in them too. Apologies, I really tried to make this not sound condescending!
  - adamisom 6y ago
    The expert you're learning from probably has a better idea than you do of what programs you should write given (a) your presumed knowledge level and (b) what programs would help you learn the fastest and/or the most relevant features. Including good exercises is an extension of the purpose of the book itself.
    - yesenadam 6y ago
KineticLensman 6y ago
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 6y ago
  >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 6y ago
    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.
- aqui_c 6y ago
  Indeed, there's no remark about it because I wanted to split the act of writing from the publishing of the book. The sentence on asking feedback was geared towards checking the ideas, having an overview of what you've written by someone else (which is not the same than proofreading). All what you mention as missing, is part of my current ongoing process, and I still haven't learned nor tested enough as to summarize it.
lmilcin 6y ago
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.
- Swizec 6y ago
  As someone who writes programming stuff, yes this! I avoid complete beginners and aim for junior to mid. The problem is that this is still a crazy fast growing field. Say we double in number every 5 to 10 years. That means at 5 years experience you are more experienced than half the industry. That’s mindboggling. Newbies also need more help and are more willing to pay for help. Oldbies only pay for help when entering a new area. Like a fortran engineer picking up React or a JS person getting into C++ One problem is that software engineering doesn’t quite value experience yet. Easier to throw 3 newbies at a problem than 1 senior who’s never seen this new tech anyway. The other issue is that engineers are smart and motivated by problem solving. They’d rather figure it out themselves than take all the fun out by just learning it like a normal person and reaping the rewards. Also advanced stuff often gets so in the weeds that only you and 50 of your friends in the whole world even care. Or it’s so specific to your company tht only other people at your company care.
  - sitkack 6y ago
    That is why there is a small time window for smallish niches, like Elixir, Clojure or Rust. One has to have their eye one fashion, the crowds, the knowledge gap and the perceived utility. I personally wouldn't wanting to be competing with all the other beginner material and sufficiently advanced material would take forever to produce. But if there was a 100 page book on writing an Elixir/Phoenix app and deploying it on K8s across 4 cloud providers, using a CDN and Aerospike, I'd pay 50$ for that.
billme 6y ago
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.
- freedomben 6y ago
  I love buying pre-releas books from Prag Prog (which isn't exactly the same but similar to what you described). Especially since things change so fast, if you have to wait for a finalized, published version of the book, it's usually outdated by the time it even hits the shelves (not entirely of course, but parts of it). If the author(s) publish pre-releases frequently, it can be a fantastic reference.
  - billme 6y ago
    Preselling good, since sending cash is a lot better signal of interest than handing over email, SMS, etc. That said, you would need to have a quantifiable definition of done and likely be a good idea to account for absolute failure in case something comes up an “done” is never accomplished. Until it is “done” likely be good idea to escrow the funds, but then you run into issue like paying taxes, transaction fees, etc.
    - freedomben 6y ago
      Agreed, escrowing is a great idea. In the case of the books I bought they were by very prominent people so I had high confidence they would be completed. For less-known authors tho, you make a great point.
Syzygies 6y ago
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.
- assadk 6y ago
  I found this quite insightful. Thank you.
- redtexture 6y ago
  I would be interested in what materials you come up with, and what resources you are looking at to make your course up. Syllabus.
- 6y ago
sideshowb 6y ago
"...in 24 hours"
csours 6y ago
> "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 6y ago
  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 6y ago
    It's about IT for Mfg, so kind of broad. Sorry about the spark plugs. Packaging is a bitch.

166 points by aqui_c 6y ago

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.

JadeNB 6y ago
> Would it be possible to display text without enabling JS? No, because then how would it set up pullquotes like "If you don't set a baseline somewhere, you risk starting a book that grows backward" that you can tweet at the push of a button? (Is that really a thing? I guess it must be somewhere, but it's new to me on a (I guess) programmer's blog.)
- chrisa 6y ago
  You can't actually send a tweet at the push of a button (unless you're connected with twitter oauth with the right permissions), but what you can do (and that button does) is opens the tweet composer pre-filled with the quote, ready for you to then just hit "Tweet"
  - qznc 6y ago
    I used to do that on my blog. Example: http://beza1e1.tuxen.de/team_building.html http://beza1e1.tuxen.de/team_building.html Stopped doing it as I got negative feedback about it being annoying. I never tracked how many tweets I get out of it though. So if you aim for popularity (unlike me) it might still be worth it. It was one of the big reasons I used RestructuredText as markup language for my static website generator. It is extensible enough to make these tweet-blocks with just: .. tweetable :: Psychological Safety is THE core factor for Great Teams says Google
- aqui_c 6y ago
  They are just links to Twitter, no JS involved on those fragments.
dorkwood 6y ago
Someone needs to make a Hacker News bingo card. "Doesn't work with JS disabled" would definitely be on there.
- throwaway_pdp09 6y ago
  Along with "you need JS for the modern web"
  - clarry 6y ago
    "it's just text and images"
aqui_c 6y ago
I'm working on that. I just used a stock template for the website.
- carapace 6y ago
  Cheers! Much appreciated. :-)
- dkersten 6y ago
  The low contrast text is also really hard to read.
carapace 6y ago
Yeah, I'm getting pretty sick of sites that want to run JS to show static content.

Vaslo 6y ago

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 6y ago
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 6y ago
  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.
yesenadam 6y ago
Gee, write a program using what you just learnt and see if it works. You want someone to tell you what program to write?! I assume it's a book for kids, or a school textbook, when I see exercises like that. I don't understand the demand that books not only tell you things, but tell you how to learn everything in them too. Apologies, I really tried to make this not sound condescending!
- adamisom 6y ago
  The expert you're learning from probably has a better idea than you do of what programs you should write given (a) your presumed knowledge level and (b) what programs would help you learn the fastest and/or the most relevant features. Including good exercises is an extension of the purpose of the book itself.
  - yesenadam 6y ago

KineticLensman 6y ago

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 6y ago
>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 6y ago
  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.
aqui_c 6y ago
Indeed, there's no remark about it because I wanted to split the act of writing from the publishing of the book. The sentence on asking feedback was geared towards checking the ideas, having an overview of what you've written by someone else (which is not the same than proofreading). All what you mention as missing, is part of my current ongoing process, and I still haven't learned nor tested enough as to summarize it.

lmilcin 6y ago

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.

Swizec 6y ago
As someone who writes programming stuff, yes this! I avoid complete beginners and aim for junior to mid. The problem is that this is still a crazy fast growing field. Say we double in number every 5 to 10 years. That means at 5 years experience you are more experienced than half the industry. That’s mindboggling. Newbies also need more help and are more willing to pay for help. Oldbies only pay for help when entering a new area. Like a fortran engineer picking up React or a JS person getting into C++ One problem is that software engineering doesn’t quite value experience yet. Easier to throw 3 newbies at a problem than 1 senior who’s never seen this new tech anyway. The other issue is that engineers are smart and motivated by problem solving. They’d rather figure it out themselves than take all the fun out by just learning it like a normal person and reaping the rewards. Also advanced stuff often gets so in the weeds that only you and 50 of your friends in the whole world even care. Or it’s so specific to your company tht only other people at your company care.
- sitkack 6y ago
  That is why there is a small time window for smallish niches, like Elixir, Clojure or Rust. One has to have their eye one fashion, the crowds, the knowledge gap and the perceived utility. I personally wouldn't wanting to be competing with all the other beginner material and sufficiently advanced material would take forever to produce. But if there was a 100 page book on writing an Elixir/Phoenix app and deploying it on K8s across 4 cloud providers, using a CDN and Aerospike, I'd pay 50$ for that.

billme 6y ago

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.

freedomben 6y ago
I love buying pre-releas books from Prag Prog (which isn't exactly the same but similar to what you described). Especially since things change so fast, if you have to wait for a finalized, published version of the book, it's usually outdated by the time it even hits the shelves (not entirely of course, but parts of it). If the author(s) publish pre-releases frequently, it can be a fantastic reference.
- billme 6y ago
  Preselling good, since sending cash is a lot better signal of interest than handing over email, SMS, etc. That said, you would need to have a quantifiable definition of done and likely be a good idea to account for absolute failure in case something comes up an “done” is never accomplished. Until it is “done” likely be good idea to escrow the funds, but then you run into issue like paying taxes, transaction fees, etc.
  - freedomben 6y ago
    Agreed, escrowing is a great idea. In the case of the books I bought they were by very prominent people so I had high confidence they would be completed. For less-known authors tho, you make a great point.

Syzygies 6y ago

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.

assadk 6y ago
I found this quite insightful. Thank you.
redtexture 6y ago
I would be interested in what materials you come up with, and what resources you are looking at to make your course up. Syllabus.
6y ago

sideshowb 6y ago

"...in 24 hours"

csours 6y ago

> "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 6y ago
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 6y ago
  It's about IT for Mfg, so kind of broad. Sorry about the spark plugs. Packaging is a bitch.