Suggestion: Add example section at end of each module

[FFX01]

I've been working through the current stable version of the book at: https://doc.rust-lang.org/stable/book/. I think the book is a fantastic resource. I've been working with higher level languages like Python and Javascript for a few years, so I am not necessarily new to programming in general, but I am new to systems level programming.

I love the depth with which the book presents different types and language constructs such as traits. I know there are a good amount of code examples currently available in the book. However, these examples come off more as snippets so to speak. I am not really sure if I'm supposed to write out the snippets and try to compile them or if they are just there for reference. So far, I have just been writing out every snippet myself and trying to use it in some way or another.

I am a firm believer in learning by doing. I believe that this concept is especially important when it comes to learning a new programming language or programming paradigm. I believe it helps a learner by reinforcing the concepts in their head and building a sort of muscle memory. This concept has been employed successfully by many other popular programming tutorials as well as many, many textbooks. At the very least, the learn by doing concept has benefited me and several people I've worked with in the past.

Therefore, I'd like to offer a suggestion:

We add a new section at the end of every module with a small program the learner is encouraged to copy by typing it out themselves. The learner should then be encouraged to compile and run the program. The program should encompass the basics of the topic presented in the module. If the learner runs into any bugs or problems, they should be encouraged to look for solutions in the docs/via search engine/rust irc/etc.

I believe this will aid the learner in fully grasping the concepts presented in the book. I also believe that the learner will inevitably run into issues and that said issues are a great way to introduce the learner to the Rust ecosystem(i.e. docs, forums, etc).

I would be more than willing to write these examples myself, but I would probably require a mentor to look over my code as, like I stated above, I am new to Rust.

[carols10cents]

Hi! Thank you so much, I'm glad you're enjoying the book!! ❤️

I am not really sure if I'm supposed to write out the snippets and try to compile them or if they are just there for reference. So far, I have just been writing out every snippet myself and trying to use it in some way or another.

There's not very much supposed to -- we'd like every reader to use the book in whatever way they find it useful. We definitely want people to be able to type in the examples and run them, as you have! Is there anything in the text that gives you the impression that you're not supposed to do that?

People learn in different ways, and I'd like us to enable everyone to learn in the way they learn best, rather than advocating for and focusing on one particular style of learning.

We add a new section at the end of every module with a small program the learner is encouraged to copy by typing it out themselves.
I've been working through the current stable version of the book at: https://doc.rust-lang.org/stable/book/.

Have you taken a look at the new book at all? While it's not quite as consistent as what you suggest, there are a few improvements that are along these lines:

• Chapter 2 builds up a complete example of the guessing game
• The end of Chapter 3 suggests some exercises that the reader should have the tools to be able to tackle
• The section introducing pub in Chapter 7 walks the reader through fixing a few errors, but leaves one and encourages the reader to try fixing it on their own
• The end of the section about pub in Chapter 7 suggests experiments to do with the code to experience how different changes affect visibility
• The end of Chapter 8 has some exercise suggestions using collections
• We're about to start working on a chapter that's about halfway through the book that will be working through a project to synthesize the concepts covered so far.

Do you think these achieve the same goals that you are advocating for here, even though they're not the same implementation you're suggesting? If not, why not?

More abstractly, more examples would be great in the book, and we'd love your help writing some. That said, we're working under a number of constraints:

• We're working through a process with our editors at No Starch Press to get the book printed. Chapters 2 and 3 are basically done at this point; we'd have to convince our editors that large changes would be worthwhile. The rest of the chapters are in the process of being finalized, so we'd need additions to early chapters very soon.
• We're trying not to use very many crates, since crates are less stable than the language. The only crate we've used so far is the rand crate. So examples should be standard library only.
• We're trying not to use concepts before we've introduced them, except for chapter 2 where the purpose is to put a project together even though we haven't covered much. I've personally found it to be difficult to construct meaningful examples with only subsets of the language in play; if you have ideas, that would be super helpful, but if you haven't tried constructing examples yet I'd like to caution that it's harder than it looks!

I'm very happy to continue discussing, mentoring, and working with you on examples, and I'd love your feedback on the new version of the book, especially the more example-ey parts highlighted above. I'm not sure that we'll be taking this suggestion exactly as you've proposed it, though. You seem enthusiastic about this, and I don't want to discourage you! At the very least, a set of examples in an online supplement to each chapter of the book would definitely be a resource people would find useful, and that could decouple the timeline of developing the examples with the publishing of the book.

Thank you for your time and thoughts! ❤️

[FFX01]

There's not very much supposed to -- we'd like every reader to use the book in whatever way they find it useful. We definitely want people to be able to type in the examples and run them, as you have! Is there anything in the text that gives you the impression that you're not supposed to do that?

No. I didn't see anything that discouraged the reader from trying out the code snippets. I do think people who may not be used to programming in languages like Rust or C may have issues if they don't understand that some of the code needs to be placed in the main function though. This may discourage them if they try to run the code and nothing happens. That said, I do believe the book does go over the fact that you need a main function earlier on.

People learn in different ways, and I'd like us to enable everyone to learn in the way they learn best, rather than advocating for and focusing on one particular style of learning.

I agree with this 100%. The reader should be encouraged to try them, but it shouldn't be enforced that they need to complete them to move on or anything.

Have you taken a look at the new book at all?

I've taken a few glances, but nothing in depth. I need to go to a meeting today, but after that i should have some time to go through the new book and the specific sections you suggested.

We're trying not to use very many crates, since crates are less stable than the language. The only crate we've used so far is the rand crate. So examples should be standard library only.

I completely understand. I like the way structs and traits are presented in the current book. I believe that creating the Circle and Square structs and implementing functions and traits for them illustrates a lot of the core concepts in Rust very well. Also, a small program like the one in the traits example could easily be expanded to become a useful graphing library.

We're trying not to use concepts before we've introduced them, except for chapter 2 where the purpose is to put a project together even though we haven't covered much. I've personally found it to be difficult to construct meaningful examples with only subsets of the language in play; if you have ideas, that would be super helpful, but if you haven't tried constructing examples yet I'd like to caution that it's harder than it looks!

I'd like to at least give it a shot. Perhaps I can start a repo with some examples and see what I come up with?

I'm very happy to continue discussing, mentoring, and working with you on examples, and I'd love your feedback on the new version of the book, especially the more example-ey parts highlighted above.

Awesome! Like I said, I'll need some time to work through the new book, but I would love to work with everyone to make this a great resource.

I'm not sure that we'll be taking this suggestion exactly as you've proposed it, though. You seem enthusiastic about this, and I don't want to discourage you! At the very least, a set of examples in an online supplement to each chapter of the book would definitely be a resource people would find useful, and that could decouple the timeline of developing the examples with the publishing of the book.

I like this approach. I'd be more than willing to help create this online resource. Perhaps that's the best way to move forward in the interest of getting the book published as soon as possible.

I'll write another comment here later on today after I've read the new book with any new ideas regarding examples. I'm going to keep in mind that any new examples should be presented in a separate online resource.

[carols10cents]

Thank you so much for understanding! I'm excited to hear your thoughts ❤️

[carols10cents]

Doing some triage, I'm going to give this a close. If you get around to making a companion resource of examples, let us know and we'll link to it! Thanks! 🌆

[skeet70]

Does your own rustlings repo not count @carols10cents :D? I'm trying to get a study group together and it seems like it'll be what we need to create good talking points for the group.

[carols10cents]

@skeet70 Rustlings is very much not complete and I haven't had much time to work on it lately :) But yeah, it'd be nice to have rustlings exercises to correspond to all chapters of the book!

Those are smaller examples that intentionally start in a non-working state, I think the original proposal here was to provide a relevant working example for each chapter. Other ideas in linked issues have been for project ideas that the reader would start from scratch. These ideas would be different from Rustlings and in an ideal world we'd have all of them available for people to choose from, but that ideal world assumes lots of time and contributions that have not magically appeared yet ;)