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

[Rob Nagler]

Nate Duehr writes:
> I sure hope they keep paying their authors and recruiting new talent, 
> because some of the best Linux documentation I've ever seen (the 
> old-school style "teach me the theory BEFORE showing me the commands" 
> kind of immersion-learning-style documentation) comes out of IBM 
> DeveloperWorks' site.
[snip]
> 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?!)

Since I'm a wannabe author, I'll chime in.  This note is long and
moralizing, but it does mention Linux at the end. :-)

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.

It's the old bottom-up vs top-down debate but applied to learning.  I
don't mind bottom-up coding, once there is a top-down understanding of
the techniques.  Bottom-up is a great way to attack a new problem
domain.  Top-down is how I need to learn new tools and techniques.
Otherwise, I end up just spinning my wheels, because I'm using my
tools ineffectively.

Looking at Amazon, you'll see that Google Hacks and books like them
are some of O'Reilly's best selling books.  People want ready-to-eat
solutions to their problems.  I think this is "haste makes waste"
thinking.

There's a similar German expression which I think captures this idea
better: Vollgas im ersten Gang (Pedal to the metal in first gear).  If
you get into a car and don't know to shift gears or even that there
are gears, you'll lose the race.  I've experienced this first-hand
with my kids riding geared bikes.  They just don't get it, and it's
non-intuitive, but you really don't want to be going down hill in your
bottom gear or up hill in your top gear.

There are quick solutions to a lot of simple problems, but pretty much
any solution works for simple problems.  You can stand up on the
pedals to get up most hills.  It's the complex problems that get you,
esp. when they look like simple problems, and the complexity creeps up
on the solution, and you haven't been adjusting your perception along
the way (aka. refactoring).  That's like starting to climb a hill in a
top gear, and all of a sudden you find it is way steeper than you
thought.  At that point, you have no choice but to go back down hill
to get in a better gear for the grade.  You don't see any bike racers
win a race that way, and my experience is that with learning and
programming you pay a much bigger price than when biking, because
ineffective habits get baked into your brain and undoing experiential
learning is very hard.

In summary, I agree with your sentiment, but I don't think that the
publishing world agrees with it.  My guess is that most technologists
want fast-food solutions, and the publishing world is writing books
for them, not us.

Relating this back to Linux: Windows is great out of the box.  Linux
is a better solution if you are in it for the long term, and you know
that the world is full of unexpected complexity.

Rob