JDK documentation

[Debra Scott]

All,

I apologize for not being clear on my original post.

The JDK documentation, that provided in the zip file we
refer to as the JDK documentation bundle, includes:

* API docs (javadocs, which are already open source as they are
    derived from the .java source files) -- I'm not referring to these
    as you already have access to changing these as part of source code
    contributions/fixes

* guides documentation (for example, see 
http://java.sun.com/javase/6/docs/technotes/guides/)

* tools (for example, see
http://java.sun.com/javase/6/docs/technotes/tools)


Do most of you only use the API docs and  are these the docs you think of?
If so, maybe it isn't worth the effort to open source the rest of our
documentation?


-Debbie



David Gilbert wrote:
> 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/

-- 

==========================================================================
Debra Scott                                 39 Golden Wheat Ln
Manager of Java SE Documentation            Wrightstown, WI  54180
Information Products Group                  Phone: 877-219-2362  x51743
Global Product Development & Operations, Sun Microsystems, Inc
==========================================================================