There is an effort that started in May-2009 which is about providing better API docs for the MC code base https://jira.jboss.org/jira/browse/JBMICROCONT-442 Recently, I came across an open source project that takes a radically different (read opposite) approach to API docs than we have with the MC code base. Mockito says: "all docs are in javadoc" http://mockito.googlecode.com/svn/tags/latest/javadoc/org/mockito/Mockito... Providing documentation in that way is easy for the consumer because it can always up to date and available online. For the provider of the docs it's also easy because docs can be changed in the same place were code changes happen. As you might guess, improving the docs of the MC code base is important and dear to me because it represents a significant non-trivial portion of our infrastructure. New comers can only make qualified changes effectively when the docs are good. views? cheers -thomas -- xxxxxxxxxxxxxxxxxxxxxxxxxxxx Thomas Diesler JBoss OSGi Lead JBoss, a division of Red Hat xxxxxxxxxxxxxxxxxxxxxxxxxxxx