On 7/23/07, Andrew Sutton <[EMAIL PROTECTED]> wrote:
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?
For my purposes, the docs are crystal clear.
b) Is it imprecise or unnecessarily wordy?
I didn't do a thorough examination, but all of the docs I examined were
precise to this intermediate C++ user.
c) Does each document "flow" correctly from one section to the next?
d) Can (should?) we provide more concrete documentation?
It is possible. For example, in the "Default Constructible" section, you
could have a section as follows:
Concrete Example of a Default Constructible:
// T t;
// T = vector<int>
// t = a
vector<int> a;
Should we? I'm not sure. I tutor a lot of students who would not be able to
use these reference documents for anything useful. Most beginners learn by
having concrete examples, and I've experienced a few blank stares by telling
beginners that an object is Assignable instead of "it overloads the equals
operator" while drawing it on the board. The question becomes, "Should
beginners bother using these docs, or should they learn elsewhere? If
they're not learning here, where else should they go to learn?"
There are plenty of beginner C++ books that don't bother with concepts, and
there are plenty of advanced C++ books that focus 100% on the standard, but
I haven't seen much in-between. This may also indicate that there's no need
for the in-between. Does anyone else have thoughts on this issue?
g) Have I obviously plagiarized anything?
I hope not ;). "The first principle is that you must not fool yourself, and
you are the easiest person to fool." Bend over backwards to cite sources
that aren't from the standard and you'll be OK.
Good work!
Jake
-------------------------------------------------------------------------
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
