Thursday, March 24, 2005

The Pragmatic Studio

For a while now, Andy and I have been giving our Pragmatic Workshop to companies around the world.Mike Clark, who wrote our Automation Book has been doing the same, running workshops on testing and automation.


So when three of us got talking, it seemed natural to see if we could bring the threads together and produce a combined workshop covering the Starter Kit essentials. The more we talked, the more fun it sounded—we wanted to put together something a bit more lively and interactive that the typical “sit and listen to someone talk” session. And we wanted to make it stick—these practices are vital to project success, and the more we could help teams come away with the will and knowledge to use them, the better.


Mike did all the work, and he’s done an incredible job. The result is the Pragmatic Studio, a series of two-day events held in cities around the country. The first is in Denver on June 20th and 21st, followed by dates in Seattle and Reston. This is just the start—if you want us to come to your town, drop Mike a note and let us know.


I’m excited about this. In the past, we needed to find companies who’d pay the full cost for us to come in and work with their teams. Now Mike’s put together events where companies can share the costs, sending as many team members as they want.


Maybe we’ll see you there…

Wednesday, March 16, 2005

The Wiki Way of Writing

Leaving dangling cross references when writing a book is like leaving dangling hyperlinks in a Wiki—they’re both a promise and a question.


I’m deep down in the bowels of writing the new Rails book. As usual, I’m adopting a fairly agile development style, moving stuff around between chapters, adding and deleting whole chapters, and generally working stuff out as I go along.



One of the tricks that I discovered myself using is the dangling cross reference. If I’m writing some introductory material, for instance, I might do something such as


  Of course, you'll need to tidy those session files. We'll talk
about this later in <pref linkend="sec.tidy.session.files"/>.

(Our books use a simple XML markup, and <pref…> creates a cross reference [including a page number] to a named tag.)


As I haven’t yet written about tidying session files, when I format the book, the cross reference shows up as


    about this later in ? on page ?.

But even better, the formatting process itself summarizes the list of all missing cross references.


This all means that as I write, I can drop in these references, not caring if the section exists. Every now and then I’ll look through the list of unknown tag names. If I’ve since written about that material, I’ll marry the text and the tag. If I haven’t I’ll know that at some point I’ll have to add more text on the subject.


In a WikiWiki web, a CamelCase word referencing an unwritten page acts as a promise of future content, and as an invitation for someone to produce that content. The same seems to apply to writing books. It’s fascinating to see the list of unfulfilled tags ebb and flow as the Rails book progresses. It’s a kind of dialectic writing process.