Thursday, August 04, 2005

Words you just never want to hear

What happens when you rush and change your modus operandi.

Email from editor:

Tom, Here it is. I think is needs a reasonably heavy edit, I’m afraid.

That is editor-speak for “this chapter stinks, fix it”.  And then when the second comment in the chapter by the reviewer is:

I would rank this chapter as the weakest link for the first volume

Ouch.  Well, one of the chapters by definition must be the weakest link.  But they were right.  What I did in this chapter was different from the rest.  It was slightly opinionated, and lacking in examples.  A recurring comment was

Here is where I think the chapter is missing a classic TK test run…

what I'm thinking about here is the classic TK introductory example that shows how to…

It was missing those, they were 100% dead on.  And in re-reading it myself, I could see it didn’t fit (the chapter didn’t). But boy, did it make for a long day.  The chapter increased in volume by 50% but is now very much reorganized, reordered and full of examples that build on each other.  I’ll not say what chapter it is (maybe we can have a contest after the book comes out to see if you can spot it from the others – I would hope not now).

It is amazing how much better it is after putting in the meat.  For whatever reason, I was just saying things (I knew them to be true, I knew what I meant), but it wasn’t coming across, it wasn’t compelling.  My favorite comment

I would so like some proof here.

I could have looked at the number of comments (over 100) versus the number of pages (about 23) and realize that ratio was bad compared to the other chapters (higher than average comment to page ratio) and “punted” – that is cosmetically fix the chapter, address the comments but not really “fix it”.  In fact, after reading the comments part way through, I closed the document and did some other stuff for a while.  Then came back and finished reading them. That was comment #58 and that was the comment that got me to say “ah hah”. 

Funny how one thing like that can set the tone.  I would so like some proof here.  That is all it took.  I said something in the text (it was true), but it sounded not plausible perhaps.  Prove it.  Show me.  Convince me.  That was all it took. 

Well, that and quite a few hours.  The chapter is longer, but it is very different.  Out with the old and in with the new – parts of the chapter were gutted, removed.  Lots of new stuff put in.  Now it is back in the review cycle for another tech edit and copy edit.

Word from the editor this morning on it:

Tom, It looks really good.

But you know, those British people are just so emotional and all – from him that is really high praise :)

7 days and counting.  Then Volume I goes off to be turned into paper – just in time for Oracle Open World in September.

POST A COMMENT

31 Comments:

Blogger David Aldridge said....

About these test cases ... what version(s) are you running them under? I suppose that the behavioural differences between 9 and 10 lead to some rather different characteristics, and when you considfer the extra features of 10 (optimization, partitioning and whatnot) it must be a pretty tiring exercise.

Thu Aug 04, 03:09:00 PM EDT  

Blogger Robert Vollman said....

Did you get a comment like this?:

"I used this chapter to line my birdcage because Polly does a much better job of summarizing my thoughts on chapters like these."

... Seriously, there are a lot of experts and authors out there. The main reason I enjoy your work is that you prove things with examples. That's honestly what makes AskTom and your books my first reference (after Oracle documentation). I learn by example, and things don't click with me until I can do it myself.

Thu Aug 04, 03:15:00 PM EDT  

Blogger Niall said....

Be sure though that if a brit says

this chapter is quite good they mean its no better than average at best. I understand that, at least in some states in the US, one could read it as a compliment.

Thu Aug 04, 03:20:00 PM EDT  

Blogger Thomas Kyte said....

what version(s)

I did them in 10gr1 and 9ir2 at least and usually in 9ir1, 9ir2 and 10gr1

Be sure though that if a brit says

well, he said really good so, it must be really good :)

Thu Aug 04, 03:24:00 PM EDT  

Blogger David Aldridge said....

That's what would really wear me down I think, the multiple version testing and correlating the results.

btrw, if he didn't say that "it's not bad" you still have some room for improvement :D

Thu Aug 04, 04:12:00 PM EDT  

Blogger Alberto Dell'Era said....

In fact I've always had this strong association of mine between "Expert" and the masterpiece of Alessandro Manzoni, one of the best italian novelists. "Expert" is the only tecnical book that resonates so strongly with that novel.

I have always wondered why; today I've understood the reason, since I checked wikipedia and discovered that "The work when published, after revision by friends in 1825-1827, at the rate of a volume a year, ..."

Light bulb switching on - continuous feedback providing the "seamless flow of thoughts" that's the common trait I noted (unconsciously) in the two works.

Oh, and the book is full of descriptions, the literary equivalent of examples of course.

Thu Aug 04, 04:33:00 PM EDT  

Blogger Jeff Hunter said....

(higher than average comment to page ratio)
I heard that if your CTP hit ratio is less than 95% you need to add more pages....or something like that.

Thu Aug 04, 04:36:00 PM EDT  

Blogger Thomas Kyte said....

I heard that if your CTP hit ratio...

that is what I did, added more pages :) it goes much faster now.

Thu Aug 04, 05:26:00 PM EDT  

Blogger Robert said....

<rant>
I've been thinking about this...is it possible to - say take an average 500-page tech book and condense it in to a "Cliff's Notes" version that's much shorter like 200-pages ?

Personally I'm just plain sick and tired of tech books that I honestly believe 50~60% of content is just "fluff" - unnecessary/repeated literature.

I absolutly need a hi-lighter when going thru a tech book and out of a whole page I usually hi-lighted just a few lines of worthy info.
<rant>

Thu Aug 04, 08:27:00 PM EDT  

Blogger Thomas Kyte said....

... Robert said... rant I've been thinking about this. ...


Robert,

just need to ask -- is this directed at either of Expert One on One Oracle or Effective Oracle by Design? Do you believe that 50-60% of them are fluff?

Because trust me, we don't get paid by the page, nor do we demand a higher price because of the page count. Not that writing books even pays that well in the first place.

(please -- no one, no one at all followup with their input on that - I'd really like to know and have an example or two. Serious, no offense taken or given or anything. I mostly feel like I haven't gone far enough in the details. Take this chapter I wrote about. It was weak. Why? It didn't show anything, it just spouted out "things I know to be true", without anyway to *see* it)

Thu Aug 04, 08:42:00 PM EDT  

Blogger Kalita said....

I’ll not say what chapter it is (maybe we can have a contest after the book comes out to see if you can spot it from the others – I would hope not now).

It probably won't be that difficult to spot. This would be one of the last few chapters having 35 - 40 pages (23*1.5) :-)

Fri Aug 05, 12:51:00 AM EDT  

Blogger Tim... said....

Regarding robert's rant.

Difficult issue. I find many technical books overly verbose, but people who are just starting need more explanation than more experienced people. Unless you release two verions targetted at different audiences you have to cater for the least experienced people.

Of course the other issue is that you often think you know something, then reading the "overly verbose" description proves to you that you don't. :)

Cheers

Tim...

Fri Aug 05, 04:40:00 AM EDT  

Blogger Javier Morales said....

I'm not agree at all with that position about "what is expected from someone...".

When I read your post, I thought that It would be nice to find a chapter based on "and, now, let's take a talk about..." with no needing of ultra-testing everything.

So, I use to repit your test cases in my own envirorment (not because I don't believe you, of course, but just finding if there's something else I have to consider about, just like privileges, Oracle release, etc.). I think people should. You always show the complete solution and many people maybe don't "build the engine to find solutions", but they got "the SOLUTION" itself already made.
People become 'static' expecting the same from someone, and do exactly what people expect from you may become yourself 'static' too.

I like your work. I enjoy it. It helped me and stills. So, when you started asktom, you did something completely different of "what was expected from" someone in your position.

...I mean, I'm sure there will NEVER be an askbill.microsoft.com :)

Can't wait for your new book,
Javier

Fri Aug 05, 05:01:00 AM EDT  

Blogger Tarry said....

I partly agree with Robert's comment. And I don't mean Tom's book's. I have three of them.(Effective..,Expert 1on1 and the beginning oracle programming).

The trend lately is of couple of guys coming together writing lots of cool stuff and each one talking a lot about his experience with the technology.

There are lot of books(in general)and especially the Wiley/Wrox books lately are all rather thick and cover topics just on the surface(I mean Java here). I personally found couple of manning books good.

I guess it's important to ask yourself.
o What your level of understanding is on that subject. Beginner, Intermediate or Advanced?

o What do you want to learn and appply.

o And cross check with others who have read the books(you intend to buy).

Fri Aug 05, 06:12:00 AM EDT  

Anonymous Anonymous said....

There's a great scene in King Rat where the British officer informs an American that the fried egg is 'not bad at all' and the American is outraged - "That's the best goddam egg you've ever eaten". The Brit is confused - "That's what I said...".

The egg wasn't bad. At all.

J.

Fri Aug 05, 06:19:00 AM EDT  

Anonymous Leo Mannhart said....

Tom, so you were writing things you knew them to be true but 'forgot' to proof them.

This then has to be the chapter with all these "silver bullets" some people are eagerly looking for :-)))

hmmm, didn't Sean Dillon leave for the Redmond company? Are you preparing to leave for this "silver bullets" company where proofs are unnecessary as nobody can understand them anyway even if the proofs are faked to show the proof?
ufff .... luckily I had a look a your picture. No, you are not looking more east as I can't see a tie so for sure you would fail their dress code :-) :-) :-)

(no offend)

Fri Aug 05, 06:39:00 AM EDT  

Blogger Thomas Kyte said....

having 35 - 40 pages

they are all 35-40 pages :)

The egg wasn't bad. At all.

laugh out loud ;)

I can't see a tie

It was there -- see the blog on "I can't see a tie" :)

Fri Aug 05, 07:24:00 AM EDT  

Anonymous Anonymous said....

I'll be the contratrian: I very much appreciate your "proof and example" style. But I also think you are good writer in general, and I would like to read more of your thoughts in the more open, informal, and flowing style of the essay (as on this blog). Consider Road & Track magazine and the difference between an article where the techical editor takes a car to the track with an armload of measuring equipment, contrasted with an essay by Peter Egan. Both help me understand the world of automobiles, but although Egan certainly knows what all the numbers are he seldom mentions them in his essays.

So I would not necessarily agree that an opening chapter in a more informal, flowing style not broken up by code/output listings was a Bad Thing(tm).

sPh

Fri Aug 05, 10:12:00 AM EDT  

Blogger Robert said....

>>
Tom said...
just need to ask -- is this directed at either of Expert One on One Oracle or Effective Oracle by Design?

<<

Oh, no. Yours and a few others are the exception. These are the ones I NEVER shake head at.

And I was not talking about tech book in general not just Oracle-related.
I'd guess the "blah-blah" was not intentional...just the author got carried away or something or they are especially mindful of VERY new hands.

Fri Aug 05, 10:35:00 AM EDT  

Blogger Thomas Kyte said....

Robert said...
Tom said...


Ok, was just asking - just to get the right perspective. Guess I'm sensitive to it since this comment:

...
I trust the author and do not need long-winded code example to prove a point. ....

popped up on bookpool in reference to Effective Oracle by Design. I think they are vital (and have no plans to stop doing it :)

Fri Aug 05, 10:41:00 AM EDT  

Blogger scubajim said....

I like the examples and proof. When I was studying for Actuarial Exams I found the REA (Research and Education Associates) books invaluable. They would have a problem and then work the problem out step by step. Then move on to a harder problem and work it out step by step. The books were massive compared to Schaum's but well worth the price and text. I could always chhose to ignore some of it if I didn't need it. But when you needed it it was fantastic to have a full example.

Fri Aug 05, 12:25:00 PM EDT  

Anonymous Anonymous said....

Hi Tom,
Is this what the title of the new book going to be - Expert Oracle Database Architecture: 9i and 10g Programming Techniques and Solutions (Paperback)?

Just checking before pre-ordering at Amazon.

Ramesh

Fri Aug 05, 12:50:00 PM EDT  

Blogger Thomas Kyte said....

Yes, that is the title.

is a link to amazon

The page count is wrong, it isn't that long since this is just volume I of II

Fri Aug 05, 01:06:00 PM EDT  

Anonymous Anonymous said....

Hi Tom,
I know you might not be the right person to talk about pricing, but who is right?

From Amazon : List Price - $69.99
Selling Price - $44.09

From Bookpool: List Price- $44.99
Selling Price - $28.50

Are they both talking about the same book? Neither of the sites mentions Volume -1

Ramesh

Fri Aug 05, 01:39:00 PM EDT  

Blogger Thomas Kyte said....

I just sent a letter to my editor :) The price is *wrong* on amazon, it'll be 44.99 list (not 69.99). I'll have them fix that.

Fri Aug 05, 01:53:00 PM EDT  

Blogger Peter Tran said....

Hi Tom,

Tom, It looks really good.

Let me guess, Jonathan Lewis. :)

-Peter

Fri Aug 05, 02:52:00 PM EDT  

Blogger Thomas Kyte said....

Let me guess, Jonathan Lewis

Nope, the editor is Tony Davis of Apress. Jonathan is one of the technical reviewers.

:)

Fri Aug 05, 03:00:00 PM EDT  

Anonymous paul said....

... for those who thought Tom was God, it's nice to see he's got a British editor!
( please don't take this too seriously )

Fri Aug 05, 05:38:00 PM EDT  

Blogger R Menon said....

Tom,
These comments are "angelic" as compared to some of the (very valid) comments you gave me for my book (Especially on the objects chapter)!:)
The first effect of those comments (for me at least) was that of a heart doing titanic! But I had gone through the edits or complete rewrites of chapters (which was the case for me), the end effect was worth it!
I must say that it is still quite painful to see the comments (from you, sometimes from the editor, Tony and sometimes from the other reviewers) on some of the chapters!:)

Sat Aug 06, 09:40:00 AM EDT  

Anonymous Anonymous said....

Tom,

Your books are the ultimate point of reference for many folks out there, above the Oracle docs. An opinion is great, just make sure it appears as such.

Good to know the editors require nothing less than a stellar quality of writing. When the book is out, it carries your name, and I'm not quite sure if anybody cares about the publisher.

Please realize that your writings have become an integral part of the CS culture, and whenever a bright college grad asks me for a good book on general programming, I refer them to your site.

Please don't feel discouraged... God bless.

Mon Aug 08, 10:23:00 PM EDT  

Anonymous Anonymous said....

Very Good article , this article make some interesting points.
Tactical Flashlights
r c helicopter
video game
Tactical Flashlight

Mon Jun 23, 02:33:00 AM EDT  

POST A COMMENT

<< Home