How to write a programming book
aquicarattino.com
How to write a programming book
1–10 of 71 posts
Re: How to write a programming book
#2This 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.
Re: How to write a programming book
#3This 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.
> 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.)
Re: How to write a programming book
#4This 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.
> 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.)
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"
Re: How to write a programming book
#5One 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.
Re: How to write a programming book
#6I 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.
Re: How to write a programming book
#7One 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.
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?
Re: How to write a programming book
#8This 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.
Someone needs to make a Hacker News bingo card. "Doesn't work with JS disabled" would definitely be on there.
Re: How to write a programming book
#9I 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 w…
>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.
Re: How to write a programming book
#10What 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.