06 April 2007

SOAX: Our Toolchain for Editing and Writing

Together with Stefan I took the adventure of editing the 750+ pages (german) SOA-Expertenwissen book. It took us nearly 12 month to complete, time enough to gain some (further) experience with the various tools that helped us master this quest (btw: I'll surely talk about several aspects of the books' content in future posts here).
Let us start right at the beginning, some nice day in May 2006: Günther Fuhrmeister motivated both of us to start - and we began with sketching and refining the books' mainline, its goals, motivation and target audience. Call it distributed brainstorming what we did by then - Mindmaps (based on MindManager) provided the needed support for creativity and order. Just in case you don't practice mindmapping: start with it, no kidding!

Ok - we developed the initial structure and many ideas for prospective authors (around 40 by June/July 2006) - but how to organize that many (distributed) contributors? We used the web-only database DabbleDB to get things going: Both editors and the publisher could get a timely overview of the books' progress. It took about 2-3 month to discuss individual contributions with the designated authors, to re-align the structure according to the ongoing discussions with the authors.

When the structure stabilized and we received the first couple of contributions, we set up a subversion repository (remotely accessible) and transfered the contents of our Dabble-database to an outliner document (we editors both use Macs, so OmniOutliner was the first choice here). First little problem here: OmniOutliner documents are stored in directories (not in single files) - subversion sometimes doesn't like that... be prepared for trouble in case of conflicts...

Right - subversion saved our neck several times. Never ever begin a real-world IT project without version control in place. Never. (You DID know that, did you?)

Starting September/October, contributions (and new authors) flooded our desks. All authors stuck to Microsoft Word (tm) for their texts - but diagrams were drawn in a variety of formats (mostly Visio, Powerpoint and OmniGraffle, a few with OpenOffice). No problem here - the publisher could deal with those formats.

Mixing Word-files (doc-format) between Mac and Windows is no problem in just about 94% of all (our) cases. We had more then 50 files to deal with - 3 (three) made real trouble: Hangups and loss-of-formating - on our Macs... can you imagine our disappointment? We called NeoOffice (based on OpenOffice) to the rescue - which managed all problematic files without any disturbance. Changelogs and comments within Word files really helped all stakeholders, although version-management with Word is a nuisance. No way around manually verifying you have the correct document version at hand... which subversion could have done a lot better (merged, detected conflicts) with pure text files.

Then we began setting up the books' website. I initially used RapidWeaver - but we encountered serious problems in committing our website sources (rw3-format). RapidWeaver pretty often crashed upon trying to open updated files - therefore we had to compress them and check-in (commit) the zip-files. Unneccessary burden! We'll switch to the textpattern content management system (I'm still very happy with RapidWeaver for my own website, which I manage on my own... Conclusion: RapidWeaver is not ready for distributed workgroups).

My personal conclusion:

  • MindManager and OmniOutliner to structure and manage - yes, again, with pleasure.

  • Word (tm) for writing and editing: A compromise, and not a pretty good one: It distracts authors from producing contend, suffers from severe featuritis and (unneccessarily) motivates everybody (myself included!) to care about the most worthless aspect of writing: layout. We all wasted hours with layouting - let publisher care about that (they do it faster and better!).

  • Next time I will talk my publisher into some pure textual format (like markdown, textile or some of those evil xml-dialects)... just to refrain myself from that layouting mumbo-jumbo. Markup'ed files can be spell-checked as (least as) good as doc-files, changes between versions can often be resolved by subversionn.

  • Ok - once upon a time I tried DITA - which I found to be a straight overdose of markup.

  • RapidWeaver: Only for personal sites with one editor.

  • If you manage distributed teams and do NOT know skype, look for another job.

  • Writing books on a Mac is surely more fun than on other machines, but still a lot of work (oh - you could have guessed that before...).

Further references

  • A series of posts from Pragmatic Dave on writing books...

  • Frank Jagla pointed me to Ulysses - which I did not use so far, but it looks promising.