rust/comprehensive-rust
1
0
Fork 0
mirror of https://github.com/google/comprehensive-rust.git synced 2025-06-07 01:56:21 +02:00
Code Issues Releases Activity
comprehensive-rust/src/running-the-course.md

58 lines
2.9 KiB
Markdown
Raw Normal View History

Add instructions about how to run the course I think we need a chapter “before the course” which gives people some background information about how to run the course. This is the start of this chapter, we might expand it in the future as we find more things to communicate here.
2023-01-06 10:40:37 +01:00
# Running the Course
> This page is for the course instructor.
Here is a bit of background information about how we've been running the course
internally at Google.
Comprehensive Rust v2 (#1073) I've taken some work by @fw-immunant and others on the new organization of the course and condensed it into a form amenable to a text editor and some computational analysis. You can see the inputs in `course.py` but the interesting bits are the output: `outline.md` and `slides.md`. The idea is to break the course into more, smaller segments with exercises at the ends and breaks in between. So `outline.md` lists the segments, their duration, and sums those durations up per-day. It shows we're about an hour too long right now! There are more details of the segments in `slides.md`, or you can see mostly the same stuff in `course.py`. This now contains all of the content from the v1 course, ensuring both that we've covered everything and that we'll have somewhere to redirect every page. Fixes #1082. Fixes #1465. --------- Co-authored-by: Nicole LeGare <dlegare.1001@gmail.com> Co-authored-by: Martin Geisler <mgeisler@google.com>
2023-11-29 10:39:24 -05:00
We typically run classes from 9:00 am to 4:00 pm, with a 1 hour lunch break in
the middle. This leaves 3 hours for the morning class and 3 hours for the
afternoon class. Both sessions contain multiple breaks and time for students to
work on exercises.
Mention how long each course day is (#1155) Most classes run with 2.5 hours for the morning session and 2.5 hours for the afternoon session. I have tried running the course as 2 × 2.5 hours and 2 × 3 hours. My experience was that people ended up getting really worn out after spending 6 hours in total on Rust (7 hours including a lunch break). However, the experience varies from group to group, so this is just a recommendation.
2023-09-01 15:13:37 +02:00
Generalize the day-4 afternoon (#487) * Generalize the day-4 afternoon This is in preparation for adding more options for this portion of the course, and reflects an existing practice of substituting other materials for this last half-day. * address review comments
2023-03-10 09:07:36 -05:00
Before you run the course, you will want to:
Add instructions about how to run the course I think we need a chapter “before the course” which gives people some background information about how to run the course. This is the start of this chapter, we might expand it in the future as we find more things to communicate here.
2023-01-06 10:40:37 +01:00
1. Make yourself familiar with the course material. We've included speaker notes
Generalize the day-4 afternoon (#487) * Generalize the day-4 afternoon This is in preparation for adding more options for this portion of the course, and reflects an existing practice of substituting other materials for this last half-day. * address review comments
2023-03-10 09:07:36 -05:00
to help highlight the key points (please help us by contributing more speaker
notes!). When presenting, you should make sure to open the speaker notes in a
popup (click the link with a little arrow next to "Speaker Notes"). This way
you have a clean screen to present to the class.
Add instructions about how to run the course I think we need a chapter “before the course” which gives people some background information about how to run the course. This is the start of this chapter, we might expand it in the future as we find more things to communicate here.
2023-01-06 10:40:37 +01:00
Various small fixes (#1556) Plus one more substantial comment on casting.
2023-12-05 16:06:42 -07:00
1. Decide on the dates. Since the course takes four days, we recommend that you
Format all Markdown files with `dprint` (#1157) This is the result of running `dprint fmt` after removing `src/` from the list of excluded directories. This also reformats the Rust code: we might want to tweak this a bit in the future since some of the changes removes the hand-formatting. Of course, this formatting can be seen as a mis-feature, so maybe this is good overall. Thanks to mdbook-i18n-helpers 0.2, the POT file is nearly unchanged after this, meaning that all existing translations remain valid! A few messages were changed because of stray whitespace characters: msgid "" "Slices always borrow from another object. In this example, `a` has to remain " -"'alive' (in scope) for at least as long as our slice. " +"'alive' (in scope) for at least as long as our slice." msgstr "" The formatting is enforced in CI and we will have to see how annoying this is in practice for the many contributors. If it becomes annoying, we should look into fixing dprint/check#11 so that `dprint` can annotate the lines that need fixing directly, then I think we can consider more strict formatting checks. I added more customization to `rustfmt.toml`. This is to better emulate the dense style used in the course: - `max_width = 85` allows lines to take up the full width available in our code blocks (when taking margins and the line numbers into account). - `wrap_comments = true` ensures that we don't show very long comments in the code examples. I edited some comments to shorten them and avoid unnecessary line breaks — please trim other unnecessarily long comments when you see them! Remember we're writing code for slides :smile: - `use_small_heuristics = "Max"` allows for things like struct literals and if-statements to take up the full line width configured above. The formatting settings apply to all our Rust code right now — I think we could improve this with https://github.com/dprint/dprint/issues/711 which lets us add per-directory `dprint` configuration files. However, the `inherit: true` setting is not yet implemented (as far as I can tell), so a nested configuration file will have to copy most or all of the top-level file.
2023-12-31 00:15:07 +01:00
schedule the days over two weeks. Course participants have said that they
find it helpful to have a gap in the course since it helps them process all
the information we give them.
Add instructions about how to run the course I think we need a chapter “before the course” which gives people some background information about how to run the course. This is the start of this chapter, we might expand it in the future as we find more things to communicate here.
2023-01-06 10:40:37 +01:00
Generalize the day-4 afternoon (#487) * Generalize the day-4 afternoon This is in preparation for adding more options for this portion of the course, and reflects an existing practice of substituting other materials for this last half-day. * address review comments
2023-03-10 09:07:36 -05:00
1. Find a room large enough for your in-person participants. We recommend a
Update "Running the course" based on latest experience (#628)
2023-05-11 19:23:01 +02:00
class size of 15-25 people. That's small enough that people are comfortable
Add instructions about how to run the course I think we need a chapter “before the course” which gives people some background information about how to run the course. This is the start of this chapter, we might expand it in the future as we find more things to communicate here.
2023-01-06 10:40:37 +01:00
asking questions --- it's also small enough that one instructor will have
Format all Markdown files with `dprint` (#1157) This is the result of running `dprint fmt` after removing `src/` from the list of excluded directories. This also reformats the Rust code: we might want to tweak this a bit in the future since some of the changes removes the hand-formatting. Of course, this formatting can be seen as a mis-feature, so maybe this is good overall. Thanks to mdbook-i18n-helpers 0.2, the POT file is nearly unchanged after this, meaning that all existing translations remain valid! A few messages were changed because of stray whitespace characters: msgid "" "Slices always borrow from another object. In this example, `a` has to remain " -"'alive' (in scope) for at least as long as our slice. " +"'alive' (in scope) for at least as long as our slice." msgstr "" The formatting is enforced in CI and we will have to see how annoying this is in practice for the many contributors. If it becomes annoying, we should look into fixing dprint/check#11 so that `dprint` can annotate the lines that need fixing directly, then I think we can consider more strict formatting checks. I added more customization to `rustfmt.toml`. This is to better emulate the dense style used in the course: - `max_width = 85` allows lines to take up the full width available in our code blocks (when taking margins and the line numbers into account). - `wrap_comments = true` ensures that we don't show very long comments in the code examples. I edited some comments to shorten them and avoid unnecessary line breaks — please trim other unnecessarily long comments when you see them! Remember we're writing code for slides :smile: - `use_small_heuristics = "Max"` allows for things like struct literals and if-statements to take up the full line width configured above. The formatting settings apply to all our Rust code right now — I think we could improve this with https://github.com/dprint/dprint/issues/711 which lets us add per-directory `dprint` configuration files. However, the `inherit: true` setting is not yet implemented (as far as I can tell), so a nested configuration file will have to copy most or all of the top-level file.
2023-12-31 00:15:07 +01:00
time to answer the questions. Make sure the room has _desks_ for yourself and
for the students: you will all need to be able to sit and work with your
laptops. In particular, you will be doing a lot of live-coding as an
instructor, so a lectern won't be very helpful for you.
Add instructions about how to run the course I think we need a chapter “before the course” which gives people some background information about how to run the course. This is the start of this chapter, we might expand it in the future as we find more things to communicate here.
2023-01-06 10:40:37 +01:00
Generalize the day-4 afternoon (#487) * Generalize the day-4 afternoon This is in preparation for adding more options for this portion of the course, and reflects an existing practice of substituting other materials for this last half-day. * address review comments
2023-03-10 09:07:36 -05:00
1. On the day of your course, show up to the room a little early to set things
Add instructions about how to run the course I think we need a chapter “before the course” which gives people some background information about how to run the course. This is the start of this chapter, we might expand it in the future as we find more things to communicate here.
2023-01-06 10:40:37 +01:00
up. We recommend presenting directly using `mdbook serve` running on your
Format all Markdown files with `dprint` (#1157) This is the result of running `dprint fmt` after removing `src/` from the list of excluded directories. This also reformats the Rust code: we might want to tweak this a bit in the future since some of the changes removes the hand-formatting. Of course, this formatting can be seen as a mis-feature, so maybe this is good overall. Thanks to mdbook-i18n-helpers 0.2, the POT file is nearly unchanged after this, meaning that all existing translations remain valid! A few messages were changed because of stray whitespace characters: msgid "" "Slices always borrow from another object. In this example, `a` has to remain " -"'alive' (in scope) for at least as long as our slice. " +"'alive' (in scope) for at least as long as our slice." msgstr "" The formatting is enforced in CI and we will have to see how annoying this is in practice for the many contributors. If it becomes annoying, we should look into fixing dprint/check#11 so that `dprint` can annotate the lines that need fixing directly, then I think we can consider more strict formatting checks. I added more customization to `rustfmt.toml`. This is to better emulate the dense style used in the course: - `max_width = 85` allows lines to take up the full width available in our code blocks (when taking margins and the line numbers into account). - `wrap_comments = true` ensures that we don't show very long comments in the code examples. I edited some comments to shorten them and avoid unnecessary line breaks — please trim other unnecessarily long comments when you see them! Remember we're writing code for slides :smile: - `use_small_heuristics = "Max"` allows for things like struct literals and if-statements to take up the full line width configured above. The formatting settings apply to all our Rust code right now — I think we could improve this with https://github.com/dprint/dprint/issues/711 which lets us add per-directory `dprint` configuration files. However, the `inherit: true` setting is not yet implemented (as far as I can tell), so a nested configuration file will have to copy most or all of the top-level file.
2023-12-31 00:15:07 +01:00
laptop (see the [installation instructions][3]). This ensures optimal
performance with no lag as you change pages. Using your laptop will also
allow you to fix typos as you or the course participants spot them.
1. Let people solve the exercises by themselves or in small groups. We typically
spend 30-45 minutes on exercises in the morning and in the afternoon
(including time to review the solutions). Make sure to ask people if they're
stuck or if there is anything you can help with. When you see that several
people have the same problem, call it out to the class and offer a solution,
e.g., by showing people where to find the relevant information in the
standard library.
Add instructions about how to run the course I think we need a chapter “before the course” which gives people some background information about how to run the course. This is the start of this chapter, we might expand it in the future as we find more things to communicate here.
2023-01-06 10:40:37 +01:00
That is all, good luck running the course! We hope it will be as much fun for
you as it has been for us!
Generalize the day-4 afternoon (#487) * Generalize the day-4 afternoon This is in preparation for adding more options for this portion of the course, and reflects an existing practice of substituting other materials for this last half-day. * address review comments
2023-03-10 09:07:36 -05:00
Please [provide feedback][1] afterwards so that we can keep improving the
Add instructions about how to run the course I think we need a chapter “before the course” which gives people some background information about how to run the course. This is the start of this chapter, we might expand it in the future as we find more things to communicate here.
2023-01-06 10:40:37 +01:00
course. We would love to hear what worked well for you and what can be made
Generalize the day-4 afternoon (#487) * Generalize the day-4 afternoon This is in preparation for adding more options for this portion of the course, and reflects an existing practice of substituting other materials for this last half-day. * address review comments
2023-03-10 09:07:36 -05:00
better. Your students are also very welcome to [send us feedback][2]!
Add instructions about how to run the course I think we need a chapter “before the course” which gives people some background information about how to run the course. This is the start of this chapter, we might expand it in the future as we find more things to communicate here.
2023-01-06 10:40:37 +01:00
Generalize the day-4 afternoon (#487) * Generalize the day-4 afternoon This is in preparation for adding more options for this portion of the course, and reflects an existing practice of substituting other materials for this last half-day. * address review comments
2023-03-10 09:07:36 -05:00
[1]: https://github.com/google/comprehensive-rust/discussions/86
[2]: https://github.com/google/comprehensive-rust/discussions/100
[3]: https://github.com/google/comprehensive-rust#building
Reference in New Issue Copy Permalink