Open Source "Maven: The Definitive Guide" (Part 2 of 2)

Before we attract a large spike of contributors it might make sense to define some parameters of the open source definitive guide effort. In this post, I'm going to throw out a few thoughts about structure, technology, and process. In the short-term, I'm interested in getting some translation work completed, and we likely need to fix typos and cut a few point releases. This post discusses broader issues of community and technology.

git clone git://github.com/sonatype/maven-guide.git

Decentralized Version Control is Perfect for Collaborative Writing Projects - A DVCS such as git is perfect for writing projects as well-written documentation is usually produced by individuals or small groups of individuals collaborating very closely. One thing that O'Reilly has always tended to do is to focus on publishing books with a limited set of authors, or publish books where one or two editors roll-up the contributions of many authors writing separate essays. We might end up with a canonical git repository for the book that is being managed by a set of core editors. Initially, I'll probably encourage potential contributors to fork and make pull requests. I'd like to see how things work before we start recreating project structures that most are used to (one project with a bunch of committers). The promise of having a DVCS is that we could encourage forking, and that forking might be the best strategy for scaling the effort. Don't be surprised if you come to us with a great idea and we suggest you work on that idea in a fork; Don't take that as an insult. In this project forking is not (necessarily) a bad thing.

Creative Commons: Attribution - No Derivatives - Non-commercial - I just want to talk about this license up-front. We're using this license for a few reasons.

• Attribution is just sensible. I don't want someone taking this content and repackaging it as someone else's.
• No derivatives - I feel very strongly that a book stands as a complete work. I don't want to see someone remixing this content without our input.
• Non-commercial - Sonatype and our contributors have spent a great deal of time on the content, our publisher is very supportive of open writing and they do make money from the printing of the book.

It might take a group of people accustomed to the Apache Software License version 2.0 some time to consider all the angles, but I don't think that the ASLv2 is a compelling license for documentation. I anticipate having long discussions about this, but writing and publishing have always been about people. Software has a certain namelessness about it while personality is an essential ingredient in a good book. CC-BY-ND-NC protects the content and gives our publisher some incentive to print (without the NC clause any publisher could print the book).

Translators are first-class authors. The publishing industry has always treated translators as glorified production staff. You get someone to translate a text into another language and they get a small cut of the royalties, but the original author's name is on the finished product. I never felt comfortable with this. When O'Reilly DE release Maven: Das Entwicklerheft which was written by Vincent Massol and I, translated by Jochen Wiedmann, I really believe that Jochen's name should have been on the book. Same thing with the Chinese translation of the Jakarta Commons Cookbook. Once you translate a book into another language, it needs an ambassador and it is a slightly different book. We have some really great authors who have translated this book into Chinese (Juven Xu) and German (Thomas Locher). I consider both of them to be just another author. Thomas, in the course of his translation gave me a lot of feedback that affected the English version of the book, and Juven's been blogging on JavaEye for the Chinese community (which has been very interested in Nexus, BTW).

Guidelines for Attribution - When I say attribution, I'm talking about credit for writers. I want to avoid a situation where a chapter has seventy authors. I'm old fashioned in that I believe that good writing is best done by one or two people and that the most basic unit of writing is a chapter. A good chapter with a common voice requires two authors that get along and have the same vision. That being said, I do want to find a way to acknowledge the contributions of people that submit fixes for typos and small suggestions. I will be proposing a set of guidelines for attribution later this week that will include a tiered system of Reviewers, Contributing Authors, Authors, and Editors. I'm a big believer that books have real names attached and I want to make sure that we have codified a set of guidelines that recognizes this.

Making decisions, setting priorities... - We're still experimenting with different approaches to collaborative writing, but don't expect the same consensus-based process that is the norm at the ASF. I think The Apache Way is great for software, but not so great for documentation or books. I'll type up some ideas about community structures that are necessary for collaborative, open source writing projects, but I'm also just interested in seeing who is out there that might want to contribute. I'm interested in enabling the sort casual "drive-by" contribution that Matthew alluded to in his comment on Jason's earlier post, but I'm also interested in see how we can organize ourselves into a writing process that retains individual writing styles.

Legalese - Everyone who contributes non-trivial content to the book will need to sign a CLA, and we'll likely have some policies about the openness of forked repositories. If you fork the maven-guide repository, and you make a pull request, everyone who has or has had permission to that repository will likely need to sign some contributor agreement with Sonatype. I'm also leaning toward the requirement that all forked copies of the repo must remain public at all times. If your fork has ever been private, I won't be pulling those changes back into the canonical maven-guide repository. I think that transparency is an important part of the process.

Clone Away

So there you have it, we'll ease into this over time, but if you are interested in contributing and have ideas, leave a comment on this post or contact me directly. This is a new approach, I'd like to test out some ideas for developing the right project management structure for collaborative writing. Like I said above, I think DVCS is perfect for writing, I'd like to encourage forking.

git clone git://github.com/sonatype/maven-guide.git