david.gilbert at object-refinery.com
Thu Jan 10 02:00:08 PST 2008
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?
> * 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
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.
More information about the discuss