Monday Aug 25, 2008

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.

Jumping to Related Places in the NetBeans Java Editor

I learned something interesting about the NetBeans Java Editor today. Say you have an import statement (or anything else) selected, as here:

Now look at those browny-greeny marks in the right sidebar. When you click them, the cursor jumps to places where the selected item is used. So, in the case of import statements, you can click the browny-greeny mark and then find yourself in places in the code where you're doing something with that class.

I never knew that and it's pretty cool.

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
« August 2008 »
SunMonTueWedThuFriSat
     
2
4
5
6
7
11
14
17
20
23
27
29
30
31
      
Today