Example splitting

[kit-sunei]

Something I've found frustrating using the rust-by-example documentation is the tendency to lump multiple different things that are being taught or learnt into a single block of code

this often muddies the learning process, at least for me, and means that it can be easy to take away one learned concept from a piece of documentation that is attempting to teach multiple.

for example, the latest time that this has tripped me up is here: https://github.com/rust-lang/rust-by-example/blob/master/src/variable_bindings/scope.md

this specific page makes for an excellent example: in it, two concepts are attempting to be taught: scope based shadowing, which is temporary, and non-scope based shadowing, which is not temporary

when learning this, I was confused by the wording of the blurb at the top, in part because it links away to wikipedia for the non-scope-based shadowing from what I gather, and in part because it is combining the two into one example

as a result I only took away the concept of scope-based shadowing, and was confused later on by example code in the library I am dabbling with in my own learning endeavours.

for an example of the way that this can be avoided, the testcase list page is a good example: https://github.com/rust-lang/rust-by-example/blob/master/src/hello/print/print_display/testcase_list.md

in this page, the various different concepts being taught are separated, specifically to avoid confusion similar to, but different from the one I found myself falling into: there are two ways to handle the error, so both are listed differently. While I understand that one of these is not recommended to be used, the concept holds true: I do not mistake them as being different things, and get a clearer picture of both things I am being taught. if the two ways to handle errors were both in the same code, I could easily confuse them as different things, and get very lost in this instance.

I can make the change for the example of what i consider a non-ideal example, in shadowing variables, but I figured it was worth starting a discussion because many examples in rust-by-example seem to run counter to this logic, and I don't want my commit to come across rude due to the disagreement with a common method used in the project

[kit-sunei]

a final note i would make is that everyone does in fact learn differently: and an argument can be made that keeping the all-in-one examples has value. I still maintain that you can still provide both, and cover more methods of learning, providing a walkthrough of the various things being taught, and then keeping an afterward "all of what was learned here" example that is what the present page holds currently as the only option