Introducing java.eremite.org

I'd like to introduce java.eremite.org. This is a clearing house for documentation related to Open Source software development projects. I built this site in order to publish documentation and tutorials on Open Source software.

As Open Source and agile development practices grow in popularity in software development, it becomes increasingly obvious that the old method of documentation publishing isn't sufficient to cover topics in Open Source. Writing a book for six to nine months, and then releasing it to a three month shelf-life in print makes little sense when the project is under continuous development and refactoring.

Similarly, trying to publish instructive articles in technical journals, and online news sites about Open Source pits writers with the inability to update their documentation for their online audience. Because so many people are available and willing to comment about the writing on sites such as TSS and Java.net, the documentation quickly accumulates rust in conspicuous places.

For some technologies that are based on standards such as the JCP, writing in this old method is more acceptable, because there is a well-known and documented public standard for much of the API and functionality. However, developers seeking to bring implementations of these software standards to market are required to make choices in the grey-spaces of the public contract. The difficulty for technical writers in the standards-compliant Open Source space lies first in covering the broad standard APIs, and second in accurately covering the margins.

Outside the standards, however, another world is teeming and active. New projects are cropping up which are purely experimental. The projects push languages to their breaking points, and are not as concerned with implementing known standards, but in altering fundamentally what it is possible to do with software. These sort of projects are highly mutable, with shifting APIs and constantly evolving documentation.

The answer is not to write shorter books more frequently, standards with fewer ambiguities or to republish (and re-sell) slightly different versions of the same document on sites like TSS. Authors need the ability to bring high-quality documentation to the market, ensure that it remains high quality both factually and aesthetically, ensure that they are always given due credit for their efforts, and that it isn't hijacked by less professional writers.

There is, to my knowledge, no mechanism or infrastructure which presently permits this. Blogs, perhaps. But blogs are not built to be altered over time. They're built to serve as a daily log. Blogs aren't built on version control systems. Wikis are, but the "wiki culture" tends to kill quality technical documentation and wikis are also notoriously designed to present information in a single shallow context. There is to date no wiki capable of presenting and organizing information with respect to its larger context.

So, half measures are required while I continue to build this infrastructure. I've decided to install my own wiki, look toward integrating a web log plugin with it, and use that for quickly building up documentation on my most experimental Open Source projects. I expect the new infrastructure will immeasurably aid me in my work.