JDK documentation

[Lance Andersen]

Hi Debbie,,
On Jan 10, 2008, at 6:26 AM, Debra Scott wrote:

> 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
>

These javadocs cannot arbitrarily be changed as these are part of the  
specification without working through the Expert Group (or spec lead  
review at a minimum)



Regards
lance
> * 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
> = 
> = 
> = 
> = 
> ======================================================================