Tim O’Brien recently invited me to write the Android development chapter for the book Maven: The Complete Reference and the first cut is in production on the site now. Since I aim to continue to help out with the chapter and John Yeary asked me for some help about contributing I thought I just jot a few pointers down. Don’t get daunted by my post here – it is really easy.
So where do we start? Well as a regular reader of the book you can just file a bug or issue and we will take care of it. You can also get a lot of help at the support site for the books. However if you are adventurous and want to help out more you can do so easily as well.
The first thing you will have to do is get the source code – after all the books are open source licensed and freely available to anyone. The books are found on github at http://github.com/sonatype/ and in the case of the reference book at http://github.com/sonatype/maven-reference-en. With the excellent help on github you can just fork the repository and get your own copy going locally. My copy for example is at http://github.com/mosabua/maven-reference-en
Now thanks to the power of Maven and its conventions you get the book created as HTML website and PDF document by running, surprise,
mvn clean install
in the root folder of the project. After a successful run you should find the resulting PDF in e.g. maven-reference-en/mvnref-book-content/target/ and the HTML website version in maven-reference-en/mvnref-book-content/target/site/reference/public-book.html or the whole archive of it all in you local repository.
When it comes to editing the book content, you will end up writing and changing docbook xml files, which can be found in /maven-reference-en/mvnref-book-content/src/main/resources/docbook/. Docbook is a widely spread standard xml format for authoring and is pretty easy to work with. Personally I use IntelliJ IDEA, but any decent XML editor should be able interpret the DTD/schema and offer command completion and such. If in doubt about the conventions in the book, just check how something is done in a different chapter for a similar use case. I found it very productive to just write away and not worry about the layout at all. Docbook takes care of that for you. It really reminded me a lot of editing LaTeX files like I used to do at university – you just concentrate on the content. Oh and just if you really need something with buttons and more you can find tools like that too. A list can be found on the docbook site with XMLMind coming up as a good free choice IMHO. But back to TeX you could actually use LyX as well it seems 😉
One minor problem I had with the build was the http request block from http://www.oasis-open.org. The docbook plugin and therefore the build for the books needs a whole bunch of documents from http://www.oasis-open.org/docbook/xml/4.5/ and http://www.oasis-open.org/docbook/xml/4.5/ent/ and somehow Maven (or the docbook plugin or whatever) is blocked by that site (great community support guys). To work around this problem I installed lighttpd with
sudo aptitude install lighttpd
and download all files in those folders and placed them in /var/www/docbook/xml/4.5 and /var/www/docbook/xml/4.5/ent. A little line like this
127.0.0.1 www.oasis-open.org
in /etc/hosts and the build should be happy. I am running Ubuntu but I am sure your install of a simple web server hosting a bunch of files is similar.
Summarizing you can see that it is pretty easy to report problems in the books as well as actually fix things. The other books from Sonatype or also the Common Java Cookbook follow a similar pattern. With the open source licensing you can easily use the same setup and produce your own technical book and with the help of Maven you could even unit test the code samples in the book as part of the build…