Sean Landis <sean.landis <at> gmail.com> writes: > > 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.
I wrote this wrong. It should read: "...followed by descriptions of the more esoteric facets of the feature." The idea being I can go to the feature I'm interested in, read the first few paragraphs, and understand the key concepts and usage. If the feature is rich, I can continue to read for more detail on the finer points. For example, in describing Router, the use of the Route and modes might be explained later in the section because they are more specialized. > 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
