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.
