> 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
asutton@cs.k...

-------------------------------------------------------------------------
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