About java.eremite.org

java.eremite.org is a clearing house for documentation related to Open Source software development projects.

Letter from the Editor

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 classical publishing method isn't sufficient to cover topics in Open Source. Writing a book takes six to nine months. 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. Software projects are cropping up which are purely experimental. These projects can push languages to their breaking points, and often are not 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.

How am I to write quality documentation for projects like these? 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.

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, and hopefully will help others doing similar work as well.

-- Alexander Saint Croix January 14, 2006