> 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
I'm kind of looking for a mini-review of the content and
presentation. The built version of the docs can be found here:
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).
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
Boost-docs@list... Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs