I think Bob was asking about the change documentation, not the steady state documentation.
I've suggested in the past that we start the release notes at the beginning of the release cycle and have developers update them as they implement significant new features or make significant changes. Creating the release notes during the release cycle rather than at the end has the advantage that things are less likely to get forgotten (if the developers are conscientious about updating the document). Certainly as a plug-in developer I'd appreciate (expect even) an explicit list of newly deprecated or removed methods and classes. As a user, I'd appreciate a brief description of new and changed features. One could argue that much, although not all, of this information is available in the issue database if you dig hard enough, but it's not in a user friendly format. Another possibility instead of version specific release notes would be to maintain a continuous "What's New" document. These are both pretty standard and well known mechanism for conveying this type of information to users and developers. Tom > -----Original Message----- > From: Linus Tolke [mailto:[EMAIL PROTECTED] > Sent: Friday, August 11, 2006 12:09 PM > To: [email protected] > Subject: RE: [argouml-dev] API compatibility (again) > > > On where to document the API. > > Bob Tarling wrote: > ... > > Should we keep some document for this in CVS to update as required. > > My answer is, yes. > > Firstly it should be documented in the java classes by having > the API methods public/protected and the API classes and > interfaces public while the non-API methods should be default > or private. This will be generated > (nightly) into the API-version of the javadoc. This will make > sure that the code is always consistent with the > documentation since it is the same. > > If there are needs for any specific discussions it should > also be documented in the Cookbook, chapter 5 in the correct > section for the subsystem providing the API. > > /Linus --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
