

On Writing Books for Programmers - nvictor
http://the-reviews.appspot.com/article/on-writing-books-for-programmers

======
bediger
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.

~~~
cema
What about good old LaTeX?

~~~
me2i81
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.

------
fredoliveira
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
_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.

~~~
ScottWhigham
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.

------
wmat
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
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.

------
deadmansshoes
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.

