Geertjan's Blog

  • August 26, 2008

Collaborative Writing in a Distributed Environment

Geertjan Wielenga
Product Manager
Here you can read how Alex Kotchnev is putting together a few people to write a new book on Tapestry 5. I got an e-mail from him this morning, asking: "Since you're the only person that I know that has written a technical book, I was wondering if you could give me some advice about it e.g. how did you guys collaborate on the RCP book, what worked, what didn't, how did you keep the code from breaking, stuff like that..."

Well, since I've now been through a few collaborative book-writing/editing processes, all of them involving contributors who were distributed across the globe, here are my thoughts, take from them what you will, reject what doesn't make sense. I'd be interested in hearing other people's thoughts on this topic too.

First of all, what are the distinct factors that are involved in collaborative writing in a distributed environment (hereafter CWiDE, pronounced "cwide", with the "c" like a "k", the whole word rhyming with "pride")? In other words, what are my assumptions. Firstly, the collaborators (i.e., the writers/editors/reviewers) are potentially in different parts of the world and have, in the most extreme case, never seen each other before. Secondly, the type of books that we're talking about here are typically written in the collaborators' spare time (i.e., they're actually developers, but they're very enthusiastic about something, and that something forms the subject of the book). Thirdly, the collaborators (at least the writers themselves) are programmers.

So given that CWiDE is primarily carried out by programmers who don't have much time in a distributed environment, it stands to reason that the writing project should be treated as any other application development project. Why? Well, quite a lot can be automated and, since you're distributed and are unlikely to have face-to-face meetings, the more that is made to be consistent, the better. Plus, you have the know-how (i.e., you know about Ant, you know about continuous builds, you know about XML), therefore why not employ it when writing your book? Maybe set up on a project on java.net and get everyone to check in their work through Subversion or CVS, etc.

So since your writing project is comparable to an application development project, you need to find the appropriate methodologies and tools and then construct some kind of development cycle. For "Rich Client Programming: Plugging into the NetBeans Platform", we used DocBook, for which we wrote a plugin for NetBeans IDE, which is where we wrote the whole book:

And every chapter was equivalent to a Java source file that we simply checked into CVS. One nice thing was that we were able to generate HTML output from our DocBook chapters:

Plus, we were able to extend our plugin as we went along! I.e., we were writing about the NetBeans APIs, so more often than not, I applied the code I was writing about to the DocBook plugin (e.g., I created new code snippets and I extended the DocBook editor with new code generating menu items). That was kind of interesting—having the book we were writing benefit from the content that we were writing about.

So, Alex, I hope this helps and good luck with your project. On a sidenote, if anyone is interested in translating a German book into English, please drop me a line and we can set up a process as described above—plus you'll gain some knowledge about the NetBeans APIs.

Join the discussion

Comments ( 6 )
  • 害虫駆除 Tuesday, August 26, 2008


  • Varun Tuesday, August 26, 2008

    Cool stuff... :-) It would have been bit cumbersome, to write content in XML format, right?

  • Gregg Sporar Tuesday, August 26, 2008

    "we were able to generate HTML output..." Hmmm... okay, but the illustration you provide looks like .pdf, not HTML.

  • Alex Kotchnev Tuesday, August 26, 2008


    thank you, this is excellent guidance, I'm liking it quite a bit already.

    One of the things that I'm still wondering about is if you could mention something about this setup with DocBook & CVS that gave you trouble . Did merges work OK for you ? Was there anything that drove you nuts along the way (from the technology setup) ? Are there any definite pitfalls in a DocBook/CVS setup that we definitely should avoid ? How did you keep the code samples always in a good shape (e.g. always runnable) ?

  • guest Tuesday, August 26, 2008
  • Antonio Saturday, August 30, 2008

    What about integrating PDF Viewer? http://code.google.com/p/netbeans-pdfviewer/

Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.