> Sorry for quoting Andrew's entire post below, but I really want to > endorse it. I consider myself very demanding when it comes to > documentation quality, but he's thinking about this at a level beyond > where I've been. I agree 100% with the direction in which he's headed > and would happily follow him into battle. It's sort of a relief to > know he's taken up this cause because now I know I don't have to worry > (much) about it ;-)
That's quite an endorsement :) I've been slowly (very slowly) contributing to the massive body of empty documents that I've committed to the boost_docs project. So far I've managed to document the five "utility" concepts: default and copy constructible, assignable, and less than/equality comparable. I'm combining and paraphrasing three distinct sources: the original SGI docs (for basic format and content), the 2003 C++ edition (for correctness) and some of the WG docs on concepts. In fact, most of the concept docs that I've written so far have a "C++0x" section at the bottom that gives some perspective on what's probably going to happen in the future. I think its probably worthwhile to include this information since its /going/ to happen and we might want to get people ready for it - and concept docs are the place to do it. Of course, this it may be inappropriate to provide documents that straddle 17 years of standard library. (the SGI docs have a 1994 copyright). 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. I'm asking the following questions: 1. Is the documentation appropriate? a) Is it too abstract? b) Is it imprecise or unnecessarily wordy? c) Does each document "flow" correctly from one section to the next? d) Can (should?) we provide more concrete documentation? e) Can you think of examples that highlight concept usage that would be worth including. f) Are there spelling/grammar errors? g) Have I obviously plagiarized anything? 2. Is the presentation conducive to readability and comprehension? I actually couldn't think of too many presentation questions, since most of them apply to the rendering system. Basically, if you read them over and find something you don't like or that could be improved, added, or removed, I'd like to know. Also, if anybody would like to contribute... well, the more the merrier. It'll be a regular documentation party (which may be a first). Back to writing graph docs. Andrew Sutton [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
