search

dotnet / docs

This repository contains .NET Documentation.
https://learn.microsoft.com/dotnet
Creative Commons Attribution 4.0 International
4.23k stars 5.87k forks source link

Why are the explanations so Vague and Empty? #8804

Closed onguardian closed 4 years ago

onguardian commented 5 years ago

The set up is great and everything is well done, but why does it when someone explains something it feels so foreign. Why can't it be like we're going over this (subject matter), and we'll be doing this (project), and lastly the reason why we do this is because (explained).

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

thurstylark commented 5 years ago

I have a very similar issue with these docs. Specifically:

https://github.com/dotnet/docs/blob/master/docs/csharp/tutorials/intro-to-csharp/numbers-in-csharp.yml#L180-181

Double-precision means that these numbers are stored using greater precision than single-precision.

This is the only explanation of what a double-precision number is, and it contains a subset of the term itself! What does "precision" mean in this context? What's "double" about it? What uses are suited to using double-precision numbers, and what uses aren't? I'm not saying that you have to insert a lengthy discussion about number types, but at least link to the Wikipedia article on double-precision numbers if an explanation here is out of scope.

Another:

https://github.com/dotnet/docs/blob/master/docs/csharp/tutorials/intro-to-csharp/numbers-in-csharp.yml#L261-262

The M suffix on the numbers is how you indicate that a constant should use the decimal type.

Ok, but why? If not why, then when do you not use the M? What does it mean? If it's explained elsewhere, link it here. Provide more explanation than just "You have to use this incantation because that's the way it is."

markbell2410 commented 4 years ago

I'd have to agree. It tends to leave you with more questions than answers. But then again, I must be a little thick as I did spend far too long looking for interactive mode! Maybe I just need to 'Focus'!

scout208 commented 4 years ago

I think the idea is to not over-saturate the reader with too much information that's not absolutely necessary and maintain the scope of these docs to C#. You don't need to know why the M suffix is used to indicate decimal type to write C# code. Or how double-precision is actually implemented to know that double can hold a larger value than single. So as much as you might like to know the "why" of everything, these docs are really more concerned about the "how" to get you started quickly.

DJTrumpDaddy commented 4 years ago

Honestly, you can see in the code simulator what "more precision" means. If you really want to know the semantics, it's a short Bing search away.

JettoDz commented 4 years ago

I have some programming experience in other programming languages and some extra knowledge on the very core of modern computers. To think that I can code on my web browser is mindblowing as it is, because I know how much work it needs to be done in order to get a computer to recognize what you are writing (Or if you are doing anything, to begin with). If you want those extra details, you'll be learing something totally different from programming. To know what "Double-precision" means will get you to another topic in Electronics and Math, even Physics and Chemistry. So yeah, not really needed to know how to code. It's fine if you want to know all of that, but learn it if you NEED to know those differences. If "Double stores more than Integer" or "Double can handle decimals" is enough information, stick with that. You'll get to the point where double-precision and single-precision actually matter, but that is really far from the scope of this tutorials.

thurstylark commented 4 years ago

You don't need to know why the M suffix is used to indicate decimal type to write C# code. Or how double-precision is actually implemented to know that double can hold a larger value than single. So as much as you might like to know the "why" of everything, these docs are really more concerned about the "how" to get you started quickly.

These are good points. I agree that as a beginner's tutorial, a full explanation is definitely too much detail to go into at this level.

My problem is that it goes into zero detail about either of these topics. At the very least, there should be something along the lines of

Double-precision means that these numbers are stored using greater precision than single-precision. The 'precision' of these number types is related to how computers store floating point numbers in binary. A full explanation is beyond the scope of this tutorial, but all you need to know for now is that on most modern computers, double-precision numbers are used more commonly.

Something like this will introduce the surface-level of the subject, keep the tutorial succinct, and explain that these terms are actually driven by some sort of logic. Without this "connective tissue" between the term and it's underlying reasoning, it sounds more like "You can tell it's an Aspen because of the way it is."

Alternatively, just lift the last sentence from the comment by @JettoDz verbatim and slap it on the end of the paragraph:

You'll get to the point where double-precision and single-precision actually matter, but that is really far from the scope of this tutorials.

As for the M suffix, I'm still not really understanding its necessity. Considering this line from the tutorial:

decimal c = 1.0M;

The tutorial simply states that "...M is how you indicate that a constant should use the decimal type", but isn't that what decimal at the beginning of the line is supposed to do? Why does M need to be specified if I'm already assigning it to a variable of decimal type? What happens if M isn't specified when you desire a decimal constant?

The technical answers to these questions are ultimately not important. My point is that this one part about a simple suffix spawned more questions than it answered, and that's a big problem for a tutorial that doesn't require any prior knowledge or experience.

The point of a tutorial should be to demystify the subject. Maybe not all the way, but at least a little. I agree that it's not useful to have the reader deep-dive into the intricacies of C# in order to explore number types for the first time, but every tutorial should avoid "because I told you so" explanations at every opportunity.

Keeping a tutorial from overloading the reader should not come at the cost of omitting information entirely, and it doesn't have to. Acknowledging that there is more information available, along with an explicit declaration of such information being out-of-scope, allows the reader to chose to either take the plunge into the depths of the subject on their own, or continue with the reassurance that a full understanding of the subject will not affect the outcome of any of the rest of the tutorial.

0nly1ken0bi commented 4 years ago

Okay for point in reference, I agree with @thurstylark.

To my knowledge and this is from what I've picked up from numerous online tutorial videos is that the M denotes the use of currency i.e. "Money".

It would be beneficial to include what the "M" actually stood for and it's impact for beginners. As mentioned above my point of reference for this has been from external communities and online training videos not endorsed by Microsoft.

Further digging reveals the following: These discussions also shed light on this https://stackoverflow.com/questions/977484/what-does-the-m-stand-for-in-c-sharp-decimal-literal-notation and here https://stackoverflow.com/questions/44542621/what-is-the-relevance-of-m-suffix-on-a-decimal-literal where @dasblinkenlight gives a rather insightful explanation.

There's No harm in adding this little tidbit as it doesn't take away from the actual learning process.

Also, here's a more in-depth explanation https://docs.microsoft.com/en-za/dotnet/csharp/language-reference/builtin-types/floating-point-numeric-types