By Geertjan-Oracle on Aug 25, 2008
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.