Docsp 29902 revise quick reference examples #277
Conversation
There was a problem hiding this comment.
good work so far! i think some of the examples should be changed to be more intuitive. if you want to use abstract examples, try to make them as basic as possible and have the fields be x, y, z, or something like that, instead of matching points to fields. users could get confused why point DEF has an xValue for example.
source/quick-reference.txt
Outdated
| @@ -28,13 +28,13 @@ their related reference and API documentation. | |||
| .. input:: | |||
| :language: go | |||
|
|
|||
| err = coll.FindOne(context.TODO(), bson.D{{"rating", 5}}).Decode(&result) | |||
| err = coll.FindOne(context.TODO(), bson.D{{"xValue", 5}}).Decode(&result) | |||
There was a problem hiding this comment.
S: I think that this example is still a little difficult to follow. I noticed that elsewhere on this page you used sample documents that includes names -- maybe you could also use that here with an age filter or something!
Suggestion applies to all examples that use this sample data
source/quick-reference.txt
Outdated
| @@ -48,14 +48,14 @@ their related reference and API documentation. | |||
| .. input:: | |||
| :language: go | |||
|
|
|||
| cursor, err := coll.Find(context.TODO(), bson.D{{"rating", bson.D{{"$gte", 8}}}}) | |||
| cursor, err := coll.Find(context.TODO(), bson.D{{"point", bson.D{{"$gte", 8}}}}) | |||
There was a problem hiding this comment.
I: In this example, the query filter doesn't match the output. The query searches for point values gte 8, but the point field isn't numerical. In any case, see comment above for changing example
source/quick-reference.txt
Outdated
| @@ -434,16 +434,16 @@ their related reference and API documentation. | |||
| context.TODO(), | |||
| bson.D{}, | |||
| options.Find().SetProjection( | |||
| bson.D{{"vendor", 0}, {"_id",0}} | |||
| bson.D{{"point", 0}, {"_id",0}} | |||
There was a problem hiding this comment.
I: the projection sets point to 0 but the output still includes the field
S: omit the unprojected field from the output
source/quick-reference.txt
Outdated
| @@ -469,10 +469,10 @@ their related reference and API documentation. | |||
| :language: go | |||
|
|
|||
| // only searches fields with text indexes | |||
| cursor, err := coll.Find(context.TODO(), bson.D{{"$text", bson.D{{"$search", "Breakfast"}}}}) | |||
| cursor, err := coll.Find(context.TODO(), bson.D{{"$text", bson.D{{"$search", "Beagle"}}}}) | |||
There was a problem hiding this comment.
S: use an example where the search term is only part of a phrase
for example, the search term could be sports and the matched document could be
`{ "name": "Sam", "description": "I love playing sports. My favorite sports are volleyball and water polo."}
source/quick-reference.txt
Outdated
| bson.D{{"age", bson.D{{"$lt", 10}}}}, | ||
| bson.D{{"$set", bson.D{{"age", 1}}}} |
There was a problem hiding this comment.
S: there's nothing wrong with this per say, but it might be confusing for readers to see an example where youre setting the age to 1 just because its less than 10. no need to change, but just suggesting
source/quick-reference.txt
Outdated
| ) | ||
| ) | ||
|
|
||
| .. output:: | ||
| :language: go | ||
| :visible: false | ||
|
|
||
| [{type Masala} {rating 10}] | ||
| [{type English Breakfast} {rating 8}] | ||
| [{firstName Lester} ] |
There was a problem hiding this comment.
| [{firstName Lester} ] | |
| [{firstName Lester}] |
source/quick-reference.txt
Outdated
| [{"firstName": "Emily" , "Description": "I love to play sports and | ||
| walk my beagle."} ... ] |
source/quick-reference.txt
Outdated
|
|
||
| .. output:: | ||
| :language: go | ||
| :visible: false | ||
|
|
||
| [{type English Breakfast} {rating 8} ... ] | ||
| [{"firstName": "Emily" , "Description": "I love to play sports and |
There was a problem hiding this comment.
| [{"firstName": "Emily" , "Description": "I love to play sports and | |
| [{"firstName": "Emily" , "description": "I love to play sports and |
* updated examples * revised * fix * post review * final (cherry picked from commit f7d1a93)
* updated examples * revised * fix * post review * final (cherry picked from commit f7d1a93)
* updated examples * revised * fix * post review * final (cherry picked from commit f7d1a93)
* updated examples * revised * fix * post review * final (cherry picked from commit f7d1a93)
* updated examples * revised * fix * post review * final (cherry picked from commit f7d1a93)
* updated examples * revised * fix * post review * final (cherry picked from commit f7d1a93)
Pull Request Info
PR Reviewing Guidelines
JIRA - https://jira.mongodb.org/browse/DOCSP-29902
Staging
Self-Review Checklist