>-----Original Message----- >From: [EMAIL PROTECTED] >[mailto:[EMAIL PROTECTED] On Behalf Of >Andrew Sutton >Sent: 23 July 2007 15:05 >To: Boost documentation format, structure, and processing discussion >Subject: Re: [Boost-docs] stl mini-review > >I'm kind of looking for a mini-review of the content and >presentation. The built version of the docs can be found here: > >http://tinyurl.com/3x9s8a > >The actual documents include that page (there's text at the bottom), >the Utilities section, and all pages within that section.
Looking a *really* good start. >I'm asking the following questions: > >1. Is the documentation appropriate? > a) Is it too abstract? No - it needs to be correct legalize, BUT ... > b) Is it imprecise or unnecessarily wordy? No - BUT ... > c) Does each document "flow" correctly from one section >to the next? > d) Can (should?) we provide more concrete documentation? Yes & yes. > e) Can you think of examples that highlight concept >usage that would be worth including. Examples are VITAL - without this most peoples reaction is "Huh"? And there needs to be LOTS of examples, and LOTS of comments saying what the examples show, however obvious it may seem to those who write the C++ Standard ;-) What about examples of user defined types? Perhaps discuss How would you tell if something is default constructible? By Test? By examining code? > f) Are there spelling/grammar errors? Not psotted any yet ;-) > g) Have I obviously plagiarized anything? NO > >2. Is the presentation conducive to readability and comprehension? Yes. Paul --- Paul A Bristow Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB +44 1539561830 & SMS, Mobile +44 7714 330204 & SMS [EMAIL PROTECTED] ------------------------------------------------------------------------- This SF.net email is sponsored by: Splunk Inc. Still grepping through log files to find problems? Stop. Now Search log events and configuration files using AJAX and a browser. Download your FREE copy of Splunk now >> http://get.splunk.com/ _______________________________________________ Boost-docs mailing list [email protected] Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs
