Re: Subject: Re: Cocoa Book / ok, ok.
Re: Subject: Re: Cocoa Book / ok, ok.
- Subject: Re: Subject: Re: Cocoa Book / ok, ok.
- From: Chuck Toporek <email@hidden>
- Date: Mon, 9 Dec 2002 12:35:43 -0500
On Monday, December 9, 2002, at 11:15 AM, Sherm Pendley wrote:
On Monday, December 9, 2002, at 12:43 AM, R. Ecalcitrance wrote:
ok, ok. sorry. apparently, from the various off list emails I've
received,
I've touched a nerve. I'm not insinuating that Scott Anguish is
Eh? Of course not - I thought your comments reflected poorly upon the
editor, not the author.
Speaking as an editor (not of Scott's book, but here at O'Reilly), I
can tell you that file conversion is often where the shit hits the fan.
(That, and a sometimes overzealous copyeditor.)
When an author is working in Word, XML, or DocBook SGML to produce
their book, those files get converted to Frame when when the book comes
into production. "Conversion" is part voodoo, in that things can
happen, like double hyphens being converted to em-dashes, and missing
slashes from HTML/XML tags in code examples (e.g., <barf\>) suddenly
disappear. After a book gets converted, we typically have a few days to
review the conversion and find problems. We have to be really careful
to look for and catch these things, but they can sometimes slip through.
It's worth noting that Word does a lot of nasty things to text as it's
entered, one of which is auto-converting double hyphens to em-dashes
and messing around with single and curly quotes, as well as doing some
odd things with backticks. To get around this, you need to turn off all
the automatic stuff by doing the following:
1. Go to Format --> AutoFormat
2. Click on the Options button
3. AutoCorrect tab
--> uncheck "Replace text as you type"
4. AutoFormat As You Type tab
--> uncheck everything in the "Replace as you type" section
5. AutoText tab
--> uncheck "Show AutoComplete tip for AutoText, Contacts, and
dates"
6. AutoFormat tab
--> uncheck everything in the "Replace" section
Then you should be safe for working on a tech book or documentation,
because Word (foolishly) assumes we're all typing business letters.
Now, add an overzealous copyeditor into the mix, who knows that a
double hyphen in text or an editor's mark means "em-dash", and you've
got a world of trouble and hurt waiting for you. I try to have a chat
with the copyeditor when a book goes into production to let them know
what they should look for, and what they should ignore.
Finally, I think another problem is that not all editors take their
technology area seriously. Most editors are not CS majors (we're
wordsmiths), nor do they have a background in programming or
application development. We place a lot of faith in the author to know
what they're saying is right, and rely on technical reviewers to read
through the manuscript and validate what's been said. We also enlist
tech reviewers to do nothing but kick-test the code examples in the
books. When working on "Learning Cocoa with Objective-C, 2nd Ed." with
James Duncan Davidson, I personally built and ran all the code examples
in the book to make sure it did what it was supposed to, and offered
bugs and feedback to author to help make them right.
I'm not trying to make excuses for errors that have crept into a book;
I thought I'd pass along some background info on what happens on "this
end".
Try as we might, nobody's perfect, but we do our best under the
deadlines and pressures of working on multiple books. When we do find
errors after a book has been printed, we post them on our errata pages,
correct them in reprints, and update things when we publish a new
edition (just as programmers offer bug fixes and updates to their
wares).
Chuck Toporek
Mac Editor @ O'Reilly
_______________________________________________
cocoa-dev mailing list | email@hidden
Help/Unsubscribe/Archives:
http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored.