[DOCS-5402] The documentation for C# driver is INCREDIBLY poor Created: 08/May/15  Updated: 11/Jan/17  Resolved: 17/Jun/15

Status: Closed
Project: Documentation
Component/s: None
Affects Version/s: None
Fix Version/s: 01112017-cleanup

Type: Improvement Priority: Minor - P4
Reporter: Tim Hardy Assignee: Craig Wilson
Resolution: Done Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Participants:
Days since reply: 7 years, 29 weeks ago

 Description   

Please improve the documentation for the c# driver. Here is one page in particular - http://mongodb.github.io/mongo-csharp-driver/2.0/reference/driver/definitions/. I'm learning MongoDb and I find your documentation to be incredibly frustrating. You've got code examples that aren't even valid c# code and you make so many assumptions and leave so many blanks that you obfuscate what you're trying to teach. Just write out simple and COMPLETE code to illustrate your points. Naming is also VERY important. All of your tests use a mechanism called "CreateSubject<Person>" - What the heck is CreateSubject??? What does that even mean? Do you mean CreateQuery? CreateQuery MIGHT make some sense, if that's the intent, but CreateSubject makes no sense whatsoever in the english language.

I'm led to believe that your english documentation was written by a non-native english speaker.

It's so bad and has created so much frustration, that I just had to let you know. I wonder how many newbie Mongo users like myself have come to your documentation and just thrown up their hands in frustration, never to return. There are so many simple things you could change that would take so little effort it's shameful.

Please feel free to contact me for more specific examples if you'd like.



 Comments   
Comment by Emily Hall [ 27/Jul/16 ]

Closed for housekeeping on 7/27/2016 by Emily Hall.
If you require additional support, please open a new ticket for prioritization.
Thanks,
Emily

Comment by Kay Kim (Inactive) [ 09/Jun/15 ]

Oh – just lowering the priority as the site is still a work in progress and things will be scheduled as things progress.

Comment by Kay Kim (Inactive) [ 09/Jun/15 ]

Hi Tim –
as you start to learn MongoDB, you might find http://docs.mongodb.org/getting-started/csharp/ helpful. One disclaimer, though, the examples in the guide were written so that they could be executed as tests (hence, some static variables and such), so while you might not write applications quite in this manner, the examples should nonetheless help highlight some of the basic CRUD features.

Regards,

Kay Kim

Comment by Craig Wilson [ 09/May/15 ]

Hi Tim,

I'm sorry you feel that way. The docs aren't fully complete yet and can always be improved. I would never consider myself a documentation writer and, since I help write the driver, have certainly overlooked details that I take for granted that would probably be helpful. We will be introducing an examples section for common patterns that might address your issues.

For now, perhaps you could elaborate about a specific example in the documentation that is unclear and what would make it better. I can probably extrapolate from there about what would be useful in other similar sections. In addition, it would helpful to know what you are trying to do and where the API itself isn't intuitive enough to be self-guiding.

As far as the tests are concerned, subject means the subject under test (SUT). In the case of these tests, since they are called FilterDefinitionBuilderTests, the subject is the FilterDefinitionBuilder. I chose to link to the tests because I assumed that seeing actual code would be useful and informative.

Thanks for voicing your concern. Our intent is certainly to do the best we can here and your input will certainly help us get there.
Craig

Generated at Thu Feb 08 07:50:15 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.