Hi,

I'm one of the (rare?) I guess users of the C++ driver and learning how to use it has been a nightmare.

Here's a list of issues I found:
--------------------------------
1. The file, bsondemo.cpp is not actually on github (or the mutlitude of links on mongodb.org do not point to it)

• Almost all of your documentation points the user to this "example" - which does not exist.
  2. You should provide more examples, one common case is when a user is modifying an object in the database.
• Querying, updating, inserting etc. that relate to the _id field are prolematic, as they rely on the user's use of mongo::OID object properly
  This has not been documented, there's no examples, and your doxygen docs are somewhat innacurate most of the time.
  Significant time to discover what should be a simple operation.
  3. More examples. There's a tiny splattering of 3-4 lines of code which infer a few simple use cases.
  4. The BSON_ARRRAY macro is barely documented at all.
• example: How to create an empty BSON_ARRAY() object? ie: All examples assume that the BSON_ARRAY being created has an element. Trying:
  BSON_ARRAY()
  BSON_ARRAY([])
  vector<mongo::BSONElement> v; BSON_ARRAY(v)

None of those natural and intitive guesses work, but creation of an empty array is a pretty standard thing to do if you're setting up something to push data into.

5. work with someone to develop use cases for "new users" and try to document some of their common issues.
6. Review your mongodb.org page and where you see the page says, "This page documentation is out of date, but the general ideas hold" and actually update, once a user gets past the general concepts, we actually need to know syntax. Especially since none of it is documented.

7. review zeroMQ's "the guide" as an example of decent documentation, examples in multiple languages, and a relatively complete attempt to anticipate the pitfalls new users would run into and provide reasonable information to them.