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

1. 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.
2. 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).
3. A Ruby script converts the Markdown chapters to HTML with some processing, most notably parsing the code segments using CodeRay.
4. 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.

Thanks so much to those of you that commented on the book design—I appreciate your time and good taste, especially Brandon Martinez, who went far enough as to create his own mock up.

Overall, the general idea was to make the design cleaner and lighter, with fewer different elements.

I made the following changes—obviously Brandon’s design was an inspiration here.

• The body text is now 12 point Century Gothic. The code text is now 12 point monaco.
• The headers and footers are now also Century Gothic.
• Code syntax highlighting is now being done with CodeRay. This gives line numbers on each code sample, and I think is a slightly less garish set of colors, though I may go in and tweak that further.
• The blue sidebar box is gone now, sidebars are now denoted by a line under the header, and a smaller, justified font.

I like this better, which was the point of asking for comments in the first place. I hope you also like it better. Same two pages, more or less.

Page One

Page Two

Upcoming: a description of the tool set I’m using to generate the PDF files, and why I think it’s not crazy.

Here are two things that may or may not be related:

1. I get to create the entire layout of this book.
2. The tutorial is running a little bit longer than I expected.

The length of the tutorial is due to one or more of the following:

1. I’m being too long winded and making this too complicated. This tends to work itself out as I go through several drafts.
2. I’m getting caught up in the weeds and details of the actual application that don’t relate to testing.
3. The page layout that I’m using is not putting enough content on a PDF page. This doesn’t affect the amount of content, but could make the book less useful.

In the past, my thoughts about book design have mostly been limited to complaining about the design of the Pro Rails Book—I’m not a huge fan of Wrox’s layout.

It seems like a good idea to try some user-testing on the book layout, since it’s under my control and relatively easy to change. So here are two screen shots of pages from the current version of the tutorial PDF:

Page One

Page Two

I’m looking for your thoughts on issues like the font size, sidebar layout, code coloring, and the like. The basic layout comes from the boom! CSS microformat and has also been used by PeepCode and Envy Casts, but I’ve modified the fonts and layout quite a bit. (The overall work flow is based on these scripts, but again, I’ve messed with them a bit.)

If you’re a font, layout, and design geek, I’d love to get your opinion.

• The body font is 12 point Lucida Grande
• The code font is 12 point Inconsolata, and coloring is handled by Ultraviolet.
• The header and footer font is from Comicraft—it’s their Dave Gibbons font.

Thanks for looking—I’d love to know what you think.