4 ms·

On Writing Books for Programmers

38 points by nvictor 16y ago

bediger 16y ago
This article makes a ton of good points, but misses typesetting. A lot of the books he cites got typeset with troff. Certainly all of Kernighan's books, and all of Stevn's books, got typeset using troff. It's not that troff is so great at user input (it's not, it's frighteningly difficult) but that the output is so good. I know that Stevens tweaked the troff to get good output, too. No orphans, widows or rivers for him. Books typeset using "Word" are typically, though not always, not good books. Word's output is usually a little goofy. Word also seems to tempt people into doing stupid things, too. Maybe Word is too easy, and authors end up writing too much, but something causes Word-set books to be a bit worse in general than other typesetting-method-books.
- beej71 16y ago
  Word processors are just not typesetting/page layout tools, generally. Plus, good page layout is hard. I certainly have plenty of bad examples on my shelf--not that I'm brilliant at it myself, or anything.
- cema 16y ago
  What about good old LaTeX?
  - me2i81 16y ago
    troff is kind of long in the tooth these days as its niche has been mostly taken over by TeX/LaTeX. The only place I ever see nroff/troff used nowadays is Unix manpages. Old Bell Labs guys probably still use troff. Just keep in mind that you don't have to use Knuth's fonts to use TeX, just as you don't have to use Times Roman to use troff.
wmat 16y ago
Great article. I particularly like the advice to keep the length of the book short. However, what do you do when you can't, break it into separate Volumes like Knuth's, TAoCP?
- ddbeck 16y ago
  Volumes, sure, but those volumes need to specialize and, to a certain extent, stand alone. In other words, don't just put "to be continued" at the end of a chapter; find a logical place to segment your work.
fredoliveira 16y ago
This is actually quite timely advice, as I'm co-authoring a book for O'Reilly right now. I do question one of the points made about book length, though - do people really prefer smaller books? This is purely based on my perspective (so should be taken with a grain of salt) but I assumed that people prefer larger volumes because it gives them the warm fuzzy feeling (tm) that they're going to find whatever they need inside. (We are going with a small-ish book, however.) Any thoughts? Thanks guys!
- davidmathers 16y ago
  people prefer larger volumes because it gives them the warm fuzzy feeling (tm) that they're going to find whatever they need inside That's how I felt when I was a novice. It didn't take to long to realize that most large books are padded with filler though. Not only did I find much of the content useless, I found the lack of concision made them harder to learn from. do people really prefer smaller books Absolutely. If I see a large book at the bookstore I don't even bother taking it off the shelf. Reference books are the exception, but I mostly use the web for reference.
  - fredoliveira 16y ago
    Thanks for your thoughts. I do prefer smaller books myself, but I keep seeing people buying large reference books which end up being wasted money in a time of Google search.
  - ScottWhigham 16y ago
    This doesn't seem correct to me. This seems exactly opposite of "correct" and feels more like, "This is what I like so therefore it must be 'right'." Walk into a bookstore or browse an online bookstore. Find the most popular/stocked books. What are they: big, small, in-between? This can't be hard to find out for yourself. If you truly care about making something that "the people want", then do your research and find out what "the market" is buying; don't just depend on one guy's answer on HN to control how you write/steer your book. And David - I mean no disrespect by this. I'm not trying to single you out; I feel the same way as you about books I want today. However I do disagree that "people" prefer small books.
deadmansshoes 16y ago
While short snippets of code to illustrate a point are useful, I find the reams of pages devoted to entire sample programs pointless. When does anyone have the time or incliniation to go the an associated website download and compile code, whilst reading a book? I also see little point in reading a book on a subject until you've at least played with the technology yourself.

38 points by nvictor 16y ago

This article makes a ton of good points, but misses typesetting. A lot of the books he cites got typeset with troff. Certainly all of Kernighan's books, and all of Stevn's books, got typeset using troff. It's not that troff is so great at user input (it's not, it's frighteningly difficult) but that the output is so good. I know that Stevens tweaked the troff to get good output, too. No orphans, widows or rivers for him. Books typeset using "Word" are typically, though not always, not good books. Word's output is usually a little goofy. Word also seems to tempt people into doing stupid things, too. Maybe Word is too easy, and authors end up writing too much, but something causes Word-set books to be a bit worse in general than other typesetting-method-books.

beej71 16y ago
Word processors are just not typesetting/page layout tools, generally. Plus, good page layout is hard. I certainly have plenty of bad examples on my shelf--not that I'm brilliant at it myself, or anything.
cema 16y ago
What about good old LaTeX?
- me2i81 16y ago
  troff is kind of long in the tooth these days as its niche has been mostly taken over by TeX/LaTeX. The only place I ever see nroff/troff used nowadays is Unix manpages. Old Bell Labs guys probably still use troff. Just keep in mind that you don't have to use Knuth's fonts to use TeX, just as you don't have to use Times Roman to use troff.

wmat 16y ago

Great article. I particularly like the advice to keep the length of the book short. However, what do you do when you can't, break it into separate Volumes like Knuth's, TAoCP?

ddbeck 16y ago
Volumes, sure, but those volumes need to specialize and, to a certain extent, stand alone. In other words, don't just put "to be continued" at the end of a chapter; find a logical place to segment your work.

fredoliveira 16y ago

This is actually quite timely advice, as I'm co-authoring a book for O'Reilly right now. I do question one of the points made about book length, though - do people really prefer smaller books? This is purely based on my perspective (so should be taken with a grain of salt) but I assumed that people prefer larger volumes because it gives them the warm fuzzy feeling (tm) that they're going to find whatever they need inside. (We are going with a small-ish book, however.) Any thoughts? Thanks guys!

davidmathers 16y ago
people prefer larger volumes because it gives them the warm fuzzy feeling (tm) that they're going to find whatever they need inside That's how I felt when I was a novice. It didn't take to long to realize that most large books are padded with filler though. Not only did I find much of the content useless, I found the lack of concision made them harder to learn from. do people really prefer smaller books Absolutely. If I see a large book at the bookstore I don't even bother taking it off the shelf. Reference books are the exception, but I mostly use the web for reference.
- fredoliveira 16y ago
  Thanks for your thoughts. I do prefer smaller books myself, but I keep seeing people buying large reference books which end up being wasted money in a time of Google search.
- ScottWhigham 16y ago
  This doesn't seem correct to me. This seems exactly opposite of "correct" and feels more like, "This is what I like so therefore it must be 'right'." Walk into a bookstore or browse an online bookstore. Find the most popular/stocked books. What are they: big, small, in-between? This can't be hard to find out for yourself. If you truly care about making something that "the people want", then do your research and find out what "the market" is buying; don't just depend on one guy's answer on HN to control how you write/steer your book. And David - I mean no disrespect by this. I'm not trying to single you out; I feel the same way as you about books I want today. However I do disagree that "people" prefer small books.

deadmansshoes 16y ago

While short snippets of code to illustrate a point are useful, I find the reams of pages devoted to entire sample programs pointless. When does anyone have the time or incliniation to go the an associated website download and compile code, whilst reading a book? I also see little point in reading a book on a subject until you've at least played with the technology yourself.