JDK documentation

David Gilbert david.gilbert at object-refinery.com
Thu Jan 10 10:00:08 UTC 2008


Hi,

Debra Scott wrote:
> Hi All,
>
> I'd like to get people's thoughts on the documentation
> for the JDK platform.
>
> * How many people feel it is important for the the docs to be open
>    sourced so the community can contribute to them?
Very important.

>
>  * How many people have seen at least one occasion
>    where they would have added something to the
>    documentation, or made a correction, if they
>    had been able? (a large or small percentage?)
In the API docs, I've often spotted corner cases that aren't 
documented.  In the past, I've documented these in the GNU Classpath 
API.  I should probably start submitting patches to OpenJDK for these, 
but I wonder if that's very efficient because the changes are small and 
the process is not so lightweight as we had for GNU Classpath (that's 
not a criticism, it's just an observation, because I understand the need 
for greater rigor in the OpenJDK process).

>  * Given that we need documentation in a structured
>    format that allows for content sharing and multiple
>    delivery vehicles, does anyone have any recommendations
>    for a system that is both easily editable, like a
>    Wiki, and easily repurposable, like XML-structured
>    docs?
A few years ago, the guys at JavaLobby started an excellent initiative 
called JDocs.  They loaded up the Javadocs for the JDK and invited the 
community to annotate them with useful pointers, sample code etc.  Sun 
(or its lawyers) unfortunately squashed the initiative and it more or 
less died (JDocs is still there, but the project seemed to lose momentum 
after the Java SE APIs were removed).  Maybe you could get in touch with 
Rick Ross and Matthew Schmidt at Javalobby and ask them about it...an 
perhaps inject some new life into JDocs.

Regards,

Dave Gilbert
http://www.jfree.org/



More information about the discuss mailing list