Jerome Louvel <contact <at> noelios.com> writes: > > > Hi all, > > I agree that the reference manual shouldn't be a repeating of the Javadocs > but go beyond and around them: > - explain design choices > - describe usage contexts > - show sample code to copy and paste > > IMO, it is not intended to be read in one shot like a book but more feature > by feature depending on the user needs (beside the first introductory > chapters).
I agree with this as long as the feature descriptions are very detailed. I think a good general approach to structuring feature descriptions would be to describe the primary usage(s) of the feature up front, followed by descriptions of the more esoteric features. That way the typical user can get an answer quickly. Not every feature is rich enough to support this approach, but it seems to me there are many features in Restlet that are simple to use in the typical case but that have many nuances for advanced cases. Sean
