OT: Writing styles (was Re: [lug] Rather disturbing)

[Nate Duehr]

On Feb 27, 2004, at 6:17 AM, Rob Nagler wrote:

> Nate Duehr writes:

>> I always skim books for this now, as one of my PHP books is over 50%
>> reprinted man pages, and it came recommended "highly" by a number of
>> people -- ARGGGGH!  I ALREADY HAVE THE DARN MAN PAGES!  What I need is
>> help APPLYING that information... Authors are you listening?!)

> My publisher, O'Reilly doesn't like this style.  I have gotten into a
> lot of trouble with my book, because about half my technical reviewers
> don't like it.  They want more code up front.  There's a lot of code,
> but it's after the theory so it doesn't feel like a lot of code, I
> guess.
>
> My solution for the code-up-front readers is: read the book back to
> front.  You can do that pretty much, because the last chapter is an
> end-to-end example, and the last chapters dive into the techniques.

Umm, you may have missed my point as I didn't state it very well.  I 
see many tech books as having four main types of content :

1. Theory/technical introduction/explanation of core technology
2. Code examples, application
3. References.  (Always important... GRIN.)

And then there's the techie book that adds another section I hate:
4. Blatant plagiarism of the man pages because they're licensed in a 
way where the author is allowed to do so.

This is ultra-simplified, but I was saying I HATE #4.  Reprinting man 
pages is a waste of trees I can do myself right here with my own 
printer, and falsely makes the book look bigger on the shelves when 
there's very little real meat or new ideas, or new ways of looking at 
the issues, inside that cover.

That's what I was complaining about. I can print my own copies of 
manpages... and I avoid books that waste my time by having over 40% of 
their content nothing more than reprinted man pages -- they're easy to 
spot.  Now if the author does something novel like print the man page 
and then intersperse it with commentary and "gotchas" -- that's useful.

And I think the code examples are best kept OFF the printed page... 
code is filler too in print, if the book comes with a CD.  A few 
examples with "more on the enclosed CD" is always appreciated, and 
"also available on our website" is even more appreciated.  (I never 
seem to leave the darn CD in the jacket in the book cover and then it's 
never anywhere nearby when I hit a section of the book that I'd like to 
see the code from.  But all the machines have a Net connection!)  When 
later chapters of books are page after page after page of code for some 
very small-scale project, I shy away from those too.  I can print the 
code example out myself from the CD -- again, filler.

I hope it's interesting to other BLUG folks -- I'd be interested in 
hearing what other people like in technical books.  This just barely 
scratches the surface of my opinions about tech books.

One of my favorite examples of a "pretty good" book is the ARRL 
Handbook.  Large sections that can be read individually to grasp a 
specific topic, authors that REALLY know their stuff, and my only 
complaint is that the technology presented is always a bit dated, but 
still it's very accurate RF engineering data, indeed.  Most of ARRL's 
books are written in this style.

Nate Duehr, nate at natetech.com