[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. |
| 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 – 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. |