Chris Shiflett [04.27.07 02:51 PM]

Not all blogs are poorly written. :-)

  Michael R. Bernstein [04.27.07 03:16 PM]

/me is lurking in wait for Tim's promised graphs...

  Haacked [04.27.07 05:32 PM]

It makes sense to me. According to studies referenced by the intro to the Head First series,

"In recent studies, students performed up to 40% better on post-learning tests if the content spoke directly to the reader, using a first-person conversational style rather than taking a formal tone."

I wrote some more about this here:
http://haacked.com/archive/2007/04/27/prose-is-dead.-long-live-prose.aspx

  chromatic [04.27.07 06:16 PM]

@Haacked, It's not the informality that bothers me, it's something else I can only describe in metaphor.

If you want to teach me Haskell, for example, don't show me how it's the best language ever for calculating the Fibonacci sequence or the digits of pi or factorials lazily. If you're going to review a new Linux distribution, don't spend four out of your five pages talking about installation and then say that BeOS had a better interface than anything before or since and conclude that you still prefer Mac OS X. If you want to sell me on a new Ruby library, don't use the word "DSL" at all. Ever.

That's tired, banal writing, and count how many times you see any of those in a given week online. If we (O'Reilly) can't explain things with better examples and draw more insightful conclusions in our books and articles and weblogs and conferences, we might as well stop what we're doing, because we no longer add sufficient value as editors and technologists and thinkers.

  Michael R. Bernstein [04.28.07 12:45 PM]

/me is still lurking in wait for Tim's promised graphs...

  Tim O'Reilly [04.29.07 10:17 AM]

Michael -- sorry this slipped my mind, and thanks for the reminder. Distractions are many and free minutes are few.

The graphs showing the trajectory for the two books are in a postscript to the entry above. (Our MT configuration doesn't seem to allow even me to publish images here in the comments.)

(Note for those who haven't previously seen our bookscan sales graphs. These are from data collected by Neilsen from point of sales data from major accounts, and represent approximately 70-75% of US sales or 50% of worldwide English sales. The numbers are in units sold weekly.)

  len bullard [04.29.07 11:45 AM]

One of the best technical manuals for the VW was "Volkswagen for the Complete Idiot". It was a firestarter for series that spoke directly to the uneducated garage mechanic trying to fix an engine designed from its inception to be fixable by the average idiot, but documented like it was a top of the line porsche.

1. The tone can match the level of the design if the design is right for the tone. I know that is self-referencing but... It's ok to let your personality show. Just try to remember that it is very easy to provincialize when doing that and sometimes, that is ok, but the web is a global book and in someways, a global mind. Don't forget: tolerance, compassion, self-restraint.

2. If you can't make the technology match the tone, write project books. I don't want to teach vector math and nested coordinate systems when I teach X3D. I teach them how to build something that from the first page they look at it and say, "Oh, I know what I can use that for." In some circles it is called the motivation context for learning, but really, it's just situation-based. Then you can take small jumps to the left of right and get an entirely different application.

3. If the reader is debugging your code while cutting and pasting it, you failed as a writer.

4. Tone should be a memory aid and that means entertaining writing is ok. Tone should not be an obstacle or means to prove you mastered a code list or argot (look it up), or that you couldn't resist inside jokes where inappropriate (we all do it; editors really should point these out).

5. Tone should match training. Some people really are rocket scientists and don't need the filler. They can read and apply the math fast. They are not a large market. Caveat vendor.

6. De-engfish the writing. It's an old term from technical writing days describing sentences overloaded with terms and too many dependent clauses. Some of us really do think and speak that way. Rewrite it. I know it's tedious but do it.

7. Quality == time == money. If they pay for the writing, do a better job. If they don't, do what you please (see Mungo Jerry).

8. Do have fun. Like watching a band perform, those that enjoy each other personally and what they are playing are entertaining. If they don't, no matter how well they execute the notes, the lack of fun shows and the show is boring.

len

  Tim O'Brien [04.29.07 06:37 PM]

I dislike the overly personal, chatty style of book writing, but I also dislike the idea of a technical book without voice.

It is a fine balance. Good book is Java Threads by Scott Oaks, and I also enjoy Brett M.'s books as being both dense and technical.

First person sparingly, know when to use it. IMO, nothing worse than having to wade through too many "I" statements when you are trying to follow a cookbook recipe. At the same time, the introduction is a good place for an aside or first person...but you also risk seeming formulaic.

  Michael R. Bernstein [04.30.07 12:40 PM]

Thanks for the graphs, Tim! All is forgiven... ;-)

  bellydancer79 [05.03.07 10:39 AM]

in response to len bullard..
I do agree, myself being a writer, and not a highly technical person. The 'uber genius'-may have created a new word there,but oh well, that admire are the individuals that can speak in frank and simple terms, still possess a personality and show it in how they write, speak, and more importantly be able to teach effectively so that many can learn. MANY, MANY blogs, books today are lacking that conversational tone to relate to the reader. 40% seems to be an understatement haacked. Think of how many in the U.S. population are employed in the science,math, computer fields? And for those who aren't, that formality isn't going to stick in their minds for them to actually grasp what the persons saying, the key is being able to relate to the MASS population.

For someone to just spit out numbers, knowlege, verbatim dialogue, where's the individual.? The HUMAN, the person that makes me want to read their book, their blog, their articles, is that a person, Im not saying be Mother Theresa or Bono. Give me a human anyday that embraces some personality,flair. Why did Clinton have so many forgive him for the scandal because he was able to relate to the social masses. That person that understands human nature, culture, sociology and psychology of people and not just a motherboard.
Being a college grad in the social sciences, a southern girl,and currently teaching myself the ropes of programming and development to build a health related site/network-keyword self taught with the trial and error, books, sites, stickies, post its, and all. It would be nice to have that site,book, blog that explains a few things in a simpler less technical dialogue, analogies, step by step whatever. Just my opinion and maybe some or many will understand or nod their heads in agreement or agree to disagree.and no offense meant in this post-was speaking in broad and general terms..

  Anonymous [08.24.07 08:33 PM]

Nice!