Jeff, Gregg, First thanks Jeff for not reopening the debate ;-) but to conclude it from my side. Here are my ideas and I think 'how to deal with documentation/specs' should be on the roadmap.
With both of you I agree that understanding the big picture ain't that easy and for that purpose an introductory walk-through would be the proper thing to have. Or a user/developer guide/tutorial that explains in lay-mans terms what it is all about. I can recall the Overture release had one, and the current JTSK has one for the new stuff as part of the "Jini(TM) Technology Starter Kit Overview" But specs that are required for a reimplementation or that tell you what to expect in the not that less straightforward cases (which my mind always tend to look for) should IMO be where they belong and that is close as possible to the code that I have to my avail in my IDE. I see no problem in moving most of the Lease Specification http://java.sun.com/products/jini/2.1/doc/specs/html/lease-spec.html to the package documentation of net.jini.core.lease as long as people get linked there from an overview about leasing to that package. As Gregg mentioned, the specification for javax.swing also links to the Swing tutorial. I don't see why we couldn't provide anchors to tutorial like information, as long as these tutorials are agnostic towards the framework (whether it is JTSK starter code, RIO, Seven, Harvester, etc.) and these tutorials are maintained at the River project. Marking those links as being no part of the spec is essential though. -- Mark
