What is it like to write a technical book? Plenty of food for thought from the lead author of the new edition of High Performance MySQL. It’s amazing how Word is still an integral part of most technical book projects despite its obvious inadequacies compared to a toolchain based on plain text files and Subversion (the Django Book used ReST and Subversion to great effect).
Sign in with 
OpenID
ORA used to support docbook (at least that's what I used for PSL). Don't know if they still use that.
Word processors are nice for the final layout/design work, though (computer books seldom require more specialized layout tools).
Fredrik - 20th June 2008 10:22 - #
Obvious inadequacies for whom, Simon? Copyeditors (who need to leave traces of their changes) might beg to differ.
That's been the whole problem all along. Word fits more people in the production chain than plain text or markup. Designers of systems based on plain text or markup have studiedly refused to examine the entire chain.
Dorothea Salo - 20th June 2008 13:44 - #
Dorothea, I'm intrigued. What are the problems that Word solves that can't be handled by a text-based format and a revision control system?
"Word processors are nice for the final layout/design work"
But that's not what word processors are typically used for in book publishing.
For the majority of people (i.e., non-software-developers) involved in producing a book, comparing diffs in Subversion is hell compared to Word's revision marks feature. It's the sole reason why Word proliferates as a book-writing tool.
"For the majority of people (i.e., non-software-developers) involved in producing a book"
Yeah, I should have mentioned that in my case, the non-software people came in relatively late in the process, when most of the material (and all of the code) was stable. They might have converted my Docbook to Word during copy editing etc, but I have no memory of using Word myself at any time.
(And ORA didn't use word processors for the final product, of course -- for PSL, they rendered the final product using troff.)
Fredrik - 20th June 2008 17:39 - #
Did Apress really use ReST throughout the entire production process for the Django book, btw? Even for the final "rendering"?
Fredrik - 20th June 2008 17:41 - #
A couple of years ago I heard Mark Shuttleworth give a talk about collaboration tools - in particular, how incredibly more productive information works such as lawyers and journalists would be if they had access to the collaborative capabilities that open source developers take for granted - patch, diff and revision control. E-mailing Word documents around with track changes enabled is a very poor substitute.
What really surprises me is that no one has cracked the UI problem relating to these tools yet. Opening them up to a wider audience would be a major contribution to society as a whole.
Fredrik: You'd have to ask Jacob about that. I seem to remember him talking about a tool he had written that converted ReST in to Docbook, but I might be making that up.
@Fredrik,
The book was in ReST throughout author and tech edit.
It was rendered to ODF when given to Apress for copy-edit.
I think that any feedback from copy-edit was addressed in ReST, and a new rendering sent back for final review.
(I was tech editor, but wasn't involved in that final phase of the project.)
Jeremy Dunck - 20th June 2008 19:04 - #
I love that ORA still uses troff to produce books (according to Frederic, at least). I have a well-worn copy of UNIX Text Processing, published by Hayden and written by Tim O'Reilly and Dale Dougherty, from my days doing computer manual production back in the late 80s and early 90s at AT&T. I still pull it out once in a while when I need to figure out something in sed or awk. It's currently sitting on an end table in my family room from the last time I used it.
ralph - 22nd June 2008 04:29 - #