JDK documentation

[Kelly O'Hair]

It would be nice to have anyone be able to add notes or annotations to the API docs that
aren't considered officially part of the spec, like example usage code or examples
where it doesn't work as expected, non-obvious coding gotchas etc.
This kind of wiki like data would need to be monitored or controlled in some way and
connected to the official API docs???
Just brain storming...

-kto

Andy Tripp wrote:
> 
>> 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?
> As you can probably tell, the API docs are far more important than the 
> other docs,
> at least for the non-beginners who read this mailing list. The other 
> docs seem fine to
> me. There are many other "guides" and the documentation for the tools is 
> pretty
> straightforward.
> 
> As others have pointed out, there is a huge issue around the API docs. How
> can we all contribute useful clarifications, corrections, and additions 
> without going
> through the whole JCP process? How do you maintain some reasonable control
> to keep the quality up while keeping it very simple to make changes? In 
> short,
> how do you let me quickly fix a typo in the API, but stop me from adding
> the comment "this method sucks!"
> 
> Seems like you'll have to decide whether to spend the rest of your life 
> tackling this API issue,
> or not. I don't much care what the process is for the other docs.
> 
> I've talked to Ray Gans about the API issue - he may have some ideas.
> 
> Andy