Skip to main content

community docs update..

Posted by eitan on April 22, 2005 at 8:54 AM PDT

in a article i wrote on ashkelon a few months ago, i'd mentioned the idea of resurrecting a community docs web site based on ashkelon. the original site was at, whose name always felt a little inadequate. so i checked on and lo and behold, it was available.

so i've been thinking about doing this very thing: bringing the site back, under a new (more appropriate) domain name.

then i realized that i originally wrote ashkelon primarily to serve my personal javadoc api referencing needs. i mean, i didn't design it to support large numbers of users, or for the population and update of apis to be so frequent to become a significant overhead. i personally use it to document the dozen or so apis that i happen to be using over a given period of time. when i come across another api that i want to leverage, i'll put it in my local copy of ashkelon.

the process used to go like this: download the source code, update the sourcepath, create an api xml file for it, invoke the ashkelon 'add' command to populate the db, and restart the web app. the whole process could take me 5-10 minutes at the most. for 100 apis, that's a couple of days! (ouch).

so i spent a little time to try to improve the situation. i haven't yet cut a new version of ashkelon but i've committed a fairly significant number of changes and improvements. here are a some of them:

1. sourcepath is no longer required, even discouraged. instead, ashkelon is now aware of source code repositories (svn or cvs). in the api xml file, i now specify where the repository lives. when i do an 'add' now, ashkelon will simply fetch the code for me.

2. i've had this small "apixml" script that would generate the skeleton xml for me from a javadoc package-list. that's a nice little time saver. i also keep these xml files around in ashkelon's source code repository so that others could use them.

3. i've slightly improved the post-population algorithm. adding j2se14 on my old powerbook used to take me 7 minutes. now it takes 4.

4. i've improved the web app's caching mechanism from being totally dumb to being just a little dumb. i don't technically need to restart the web app after an 'add' anymore

so now the process is a little more streamlined: create the api xml file (using the apixml tool), invoke the 'add' command. this takes me maybe 3-4 minutes now for your average api.

the dilemma is that we always generate more great ideas than we have time for. i have lots of plans for this site but who knows if i'll ever get to them. maybe as a community we can. but there are a few things that i have to do to allow to truly be a community-enabled system: giving you control over managing apis.

here's a partial to-do list, sorted by degree of importance (descending):

1. set up a system where adding or updating apis on is distributed. the api management overhead could be made minute if it were shouldered by the entire community. anyone wishing to add (or update) an api would simply complete an online form. the request would be placed on a queue and processed into ashkelon shortly thereafter, or maybe that night (i have begun working on this).

2. i wrote ashkelon back in the days before the ascent of o/rm's (hibernate et al). it's high time i totally replace direct jdbc calls with hql. for one thing it'll take care of caching for me.

3. let go of ashkelon's api xml format altogether and rely on stronger maven integration. the maven project.xml file could become the defacto source of all the information ashkelon needs to do its javadoc'ing. (actually i already have a maven project.xml adapter. but i haven't yet changed my personal practice of using the original xml format)

4. i want to take the ui's markup to a higher semantic level (yeah, i'm a ui freak). it's already highly semantic but i want to be able to make ashkelon into an ashkelon zen garden.

there you have it. an update on where i am. i know that david walend had blogged on the topic of community javadocs for i also realize the response out there was very positive. anyone interested in helping out please let me know. as with most things open source, i won't commit to a specific timeline. but now at least you know where i'm trying to go with this. thanks. / eitan

Related Topics >>