I’ll keep this short and sweet.

Rails Test Prescriptions is now on sale.

The Lulu URL is http://www.lulu.com/content/e-book/rails_test_prescriptions/6418439. Price is $9.00. Please let me know what your purchase experience is like—and keep the Lulu receipt. I might use it for update registration in the future.

I hope you like what’s there and what will be coming. Please email at railsprescriptions at gmail dot com, or use the Get Satisfaction feedback link, or comment here. Your feedback will make a huge difference in how this project proceeds.

Also, I feel a little silly mentioning this, but I also feel silly not mentioning it. If, for some reason, you feel like supporting this project beyond purchasing a copy—like, you want to distribute the book throughout your organization, there’s a PayPal donate link on this site. Funds will go toward improving the book and this site.

Thanks for all your support and kind words over the last few months.

Something happened this week that I never imagined would happen.

I received my first royalty check for Jython Essentials that I would describe as being “in the middle two figures”.

What’s amazing about this is that the book was originally released in March, 2002, and is only now beginning to earn out it’s advance.

As you probably know, in most cases a technical author is paid up front with an advance (typically somewhere in the four figure range for a non-famous author). After the book is out, the author gets a royalty, typically about 10% of the what the publisher is paid for each book—however the author only actually sees this money once the total amount of the royalty exceeds the advance. (To be perfectly clear, the author doesn’t give the advance back for low sales. Also, Pragmatic, as usual, runs a little differently).

In the case of the Jython book, about half of the sales happened in the first six months or so, and then they declined exponentially and I thought the book would stop selling long before the 6500 or so copies needed to cover the advance. However when the Jython project kick-started about a year ago, there was a noticeable uptick in sales from about 1-3 a month to about 10-20 a month, and that was enough for the book to scramble over the finish line.

So, thanks to any of you that bought the book—I hope you liked it.

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.

So, I’ve decided to write a book about testing. Which begs the question: what goes in a book about testing?

I decided almost immediately to use a format with a series of short sections, somewhat along the lines of a recipe or hacks book. A full-on narrative book following a single site would be hard to do for testing—you’d wind up bringing in all kinds of details about the site being built that would distract from the test content.

I’ve never done anything in a recipe-esque style, and I like the idea that it’s a flexible format that would be easy to expand and keep curent over time. In case I haven’t mentioned it enough times, the goal here is to keep this book from decaying—a short-section format enables that somewhat.

Having decided on that format, the “prescriptions” name came out of a thesaurus search on “recipes” to try and come up with a word that seemed suitable. I liked the health metaphor, so—name chosen. One of these days I need to register the domain for the obvious misspelling…

My own experience as a connoisseur of several recipe books is that they can be pretty hit and miss. Typically, there are some recipes that are indispensable, some others that I already know, and some that are specific and don’t apply to me. Done well, it’s worth the time and effort. Not done well, and you feel like you’ve bought a $30 dollar book for $9 of content. (I’m hoping that offering my book for $9 will mitigate this complaint somewhat…)

This begs a number of related questions. Aim the book at a beginning user, intermediate, or advanced? Focus on Shoulda or RSpec? Obviously, any decision here has an impact on who will find this book useful.

For the user question, I tried some basic user modeling and profiling techniques, ending up with the following two (oversimplified) groups that I want to satisfy.

• Beginner to intermediate programmers who know Rails, but haven’t done much testing. If the code samples I see in resumes and projects we take over is any indication, there are rather a lot of you. These readers don’t need me to define Rails concepts, but they probably would like to have a description of what testing tools are available, how to use them, and most importantly, why to use them.

• Intermediate to advanced programmers who already do testing, but are looking for a single point of reference for testing tools. These programmers probably are looking for the book to be a guide to testing some more specific cases, like, say, file uploads, they also want plain reference material, and stuff that will help persuade recalcitrant colleagues might be nice.

How to balance these? What I’m trying to do is make sure that the “basic” prescriptions, like “I need to test models” will have enough reference material to make them useful for advanced users, while making the “advanced” prescriptions something that the beginner users will be able to use as needed.

As for tools, I think this one might change over time (perhaps due to feedback from potential readers…), but the current guidelines are:

• By default, use the base Rails test facilities. The 2.2 update was helpful here in that it closed some of the gap between base Rails and RSpec/Shoulda

• Any test framework that has a significant user base will get one prescription just on how to install and use it.

• Where one of the external frameworks offers a feature that’s not in the base test set, that feature will be covered where appropriate—so RSpec’s view testing setup will be included as part of the section on view testing, Shoulda contexts are discussed in a style section on grouping setups, and so on.

I’m hoping this set of guidelines will make the book as useful as possible for as many of you as I can. But one reason for starting to talk about the book now is to get feedback about these choices while there’s still time for me to do something about it.

I’d like to read a brief statement, and then I’ll take a few questions.

Today I’m happy to announce the grand opening of Rails Prescriptions, a purveyor of fine Ruby on Rails books and book-like products.

The first book from Rails Prescriptions will be titled Rails Test Prescriptions: Keeping your application healthy, and will be available for order in January, 2009.

Rails Test Prescriptions is a comprehensive guide to automated testing for your Rails application, containing more than 30 individual prescriptions on various Rails testing features and techniques. I’ll be continually updating the book after its initial release to allow for changes in Rails, new testing tools, correction of the occasional error, and reader feedback. I want this book to stay in date as long is it has readers.

And now, your questions. I’m guessing:

What format will the book be released in?

The book will be a DRM-free PDF file. Additional formats (like a print-on-demand version) may be offered if there’s an outcry.

How long will the book be?

Not sure how meaningful this is because the page formatting is optimized for screen, but the PDF will probably wind up being around 200 pages give or take a couple dozen.

What’s the schedule and pricing?

The final book will probably be $9, and will be available sometime towards the end of January, 2009. Free samples will most likely pop up by the end of 2008 or so, and there will be a chance to buy a beta/incomplete version earlier in January, probably at some discount. But I haven’t decided on that for sure.

Once you’ve bought the book, you’ll be able to get free updates regularly for some extended period of time. I really want this book to stay up to date and useful.

January is like, weeks in the future. Why announce it now?

Because I want to hear from potential readers now. I have an outline with about 30 potential sections. But I want to know what’s important to the people that might actually buy this book. What tools would you like to see documented. What part of Rails do you find hard to test? Generally, what would make a book on Rails testing something you would actually use to make your work easier?

How can I make suggestions?

The two best ways are to email to railsprescriptions at gmail.com or head over to our Get Satisfaction link at http://getsatisfaction.com/railsprescriptions. You can also direct message me on twitter.

How can I follow the Rails Prescriptions news?

Subscribe to the Rails Prescriptions 24 Hour Window blog. Also, I’ll be updating via twitter, follow me there.

How far along is it?

Something like 30% of the first draft complete at this point.

Why this book, this way, this time?

Well here’s a funny story. I started pitching a (different) Rails book to publishers, a process that started in June ‘08, and resulted in a tentative offer toward the end of October. That required me to turn in the book in April ‘09 for publication in August ‘09. That’s a long time, especially since there’s no easy way to keep a major-publisher book up to date.

So, I thought, I can do this myself and get it out in front of people a whole lot faster than 14 months. And I could keep the book up-to-date. And choose my own tools and layout. Suddenly this started to sound like a lot of fun.

Having decided to distribute my own book, it seemed like a book on testing would be a bit more fun to start with than my original plan. (If things go well, some form of the original book will be the second Rails Prescriptions title).

Sounds great. Now what?

Thanks for reading this far. Check out the Rails Presciptions blog and the twitter feed, and watch this space for more info.