Collaborative Writing in a Distributed Environment

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.

Comments:

害虫駆除

Posted by 害虫駆除 on August 25, 2008 at 07:19 PM PDT #

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

Posted by Varun on August 25, 2008 at 10:44 PM PDT #

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

Posted by Gregg Sporar on August 26, 2008 at 12:14 AM PDT #

Geertjan,
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) ?

Posted by Alex Kotchnev on August 26, 2008 at 12:38 PM PDT #

I found the part 1 of this article:
http://blogs.sun.com/geertjan/entry/lifting_the_veil_how_the

Posted by guest on August 26, 2008 at 03:56 PM PDT #

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

Posted by Antonio on August 29, 2008 at 06:57 PM PDT #

Post a Comment:
  • HTML Syntax: NOT allowed
About

Geertjan Wielenga (@geertjanw) is a Principal Product Manager in the Oracle Developer Tools group living & working in Amsterdam. He is a Java technology enthusiast, evangelist, trainer, speaker, and writer. He blogs here daily.

The focus of this blog is mostly on NetBeans (a development tool primarily for Java programmers), with an occasional reference to NetBeans, and sometimes diverging to topics relating to NetBeans. And then there are days when NetBeans is mentioned, just for a change.

Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
12
13
14
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today