Writing Tools
I hate Microsoft Word. That’s not the only thing that caused me to want to do this book this way, but it’s in the top five.
That’s what we in the writing biz call “a grabber”. Right? Feeling grabbed?
The usual complaints about Word aside — it’s bloated, the UI is hopelessly busy, managing complicated layouts is nigh impossible… um, it’s possible I’m not leaving those complaints completely aside.
Let me try again. On top of the usual complaints about Word, it’s also spectacularly unsuited to the kind of technical writing that I’ve been asked to do using it.
My standard line about Word, which I’ve been using for about eight years, is that it was built and optimized for creation of the four-page office memo. Something short, with a small number of consistent styles that rarely, if ever, need to be specialized or changed. And without much in the way of complex layout.
Here’s how Word gets used. The publisher has a template with dozens of different styles (Wrox’s template had more than 80 styles with descriptive names like “TX” or “NL2”). Each chapter file is fifteen to forty-five pages. Nearly every paragraph has to have character stylings changed inside it for code literals or some such, and there’s not as much consistency as to what order styles come in (code paragraphs can pop in anywhere, for example). As a result, technical writing using Word tends to devolve into long fights over the styling of various elements.
On the publisher’s side, the Word documents are (I think) converted internally to whatever more powerful publishing software they use, which is why the writer needs to use the publisher’s style template. For what it’s worth, I think the publishers keep using Word because of a) Word’s change tracking facilities, extensively used during the production and editing phase, b) it’s perceived as something that everybody will have, which I’d guess is a surprise to Linux-based authors, and c) there is a large sunk investment in the scripts that convert the document files.
Anyway, when I started working on the wxPython book, Patrick and Robin had worked out a system where we wrote the book in reStructured Text. Patrick had written a script to convert the text to Open Office format using the publisher styling, and then we manually saved those files as Word files to hand in. Writing in plain text using a text editor was much easier and faster. Among other advantages, it was easier to share code across our different OSes, and it was easy to use source control for the book text. Down side was that the conversion to OO was a bit wonky, and once we turned in the final chapters for review, we were basically stuck with Word throughout the review and publishing process. Which lasted about a year, but that’s another story…
Since then, I’ve always asked what tools the publisher uses throughout any of the projects that I’ve pursued. And I’ve looked longingly at the publishers that I know use text-based tool setups (most notably Pragmatic). The IBM articles use an XML markup that I can write in a text editor, and publish locally, but with a pretty heavy markup.
In creating what I use for this book, I was very fortunate to get a pointer to the scripts used by Carlos Brando for the What’s New In Rails Books. This was a great place to start in creating a work flow. The flow looks like this
- The initial text is written using Markdown, with occasional raw HTML because some of the formatting requires specific CSS classes. I’m comfortable with Markdown and can write it pretty quickly. And I get to use TextMate or any other editor I might want in the future.
- Since it’s text, I can easily use git for version control locally on my machine, and have a complete record of all my changes. (I also use Mozy for offsite backup of the whole deal).
- A Ruby script converts the Markdown chapters to HTML with some processing, most notably parsing the code segments using CodeRay.
- A script converts the HTML to PDF with PrinceXML and a CSS style sheet with a couple of extensions to support page layouts, footnote counting, and the like. I like this because I (mostly) understand the CSS, and I find it easy to manipulate.
I’m finding this process to be quite flexible, easy to work with, and allowing me a readable text view and quick visualization of the final layout. For example, it took me about an hour and a half to make the changes between the first version and second version of the tutorial, and that includes figuring out how to incorporate CodeRay.
I’m happy with it so far — it’s much more pleasant to work with than any other of the books I’ve worked on.