Update documentation

Author: hdoordt

CONTRIBUTING.md

@@ -16,11 +16,6 @@ If you feel Rust 101 should cover a topic that is currently not covered, you can
 State the main goal and the learning objectives of the module, as well as the covered topics and proposed exercises.
 In case an addition proposal is accepted, a PR with the proposed changes referring to the relevant issue can be opened.
 
-Please use `slides/format-lectures.md` as a format for the module's lecture slides.
-The exercise description should be added in a new book chapter, by adding an entry to `exercises/book/SUMMARY.md`, pointing to a new markdown file.
-Any exercise scaffolding can be added as a new Cargo project in `exercises/[your-module]/[exercise-name]`.
-Prefix the exercise scaffolding project folders with the exercise number.
-
 Have a look at the structure of the current slides and exercises to get a better understanding of how modules are organized.
 
 ## Trying it out on your students

README.md

@@ -8,12 +8,33 @@ Why? Have a look at our [blog post](https://tweedegolf.nl/en/blog/80/rust-101-op
 
 This repo will contain everything that's needed to organize the course: slides, exercises, tools, setup instructions and more.
 
-The rendered exercises, including installation instructions, can be found at <https://101-rs.tweede.golf>
-
 *Currently highly in flux, and incomplete, but feedback and [contributions](./CONTRIBUTING.md) are welcome! So is sponsorship; read more below or on our [Sponsorship page](https://github.com/sponsors/tweedegolf).*
 
+## Usage
+Have a look at the [ModMod Readme](./modmod/README.md) for instructions on how to render the content of a track.
+
+## Structure
+The actual content can be found in the [`content`](./content) directory.
+The content is structured in a tree of Tracks, Modules, Units, and Topics.
+Tracks define a single course, which consists of one or more Modules, which again combines one or more Units, which again is a set of Topics.
+Units roughly correspond to one lecture+tutorial (or at least that is the idea, but TODO), and consist of several Topics. Related Units are combined in a Module.
+Topics are packages that cover a single topic, and include a small number of slides, some exercises, and an exercise descripion.
+Topics can define their learning objectives, further reading material, and how they should be summarized in a Unit introduction.
+
+Tracks, Modules, Units, and Topics and the files they refer to are described in the several TOML files in the [`content`](./content) directory.
+[ModMod](./modmod/README.md) combines the content into a structure that can be directly published to your students in a Git repo, for instance.
+
+## Pre-defined tracks
+- [Rust Language Introduction](./content/rust-intro.track.toml) aims to introduce the basics to the Rust programming language, and to enable students to engineer their own applications and crates.
+- [Rust for the Web](./content/rust-for-web.track.toml) covers content that is needed to use Rust in web applications.
+- [Rust for Systems Programming](./content/rust-for-systems.track.toml) contains more low-level topics, to teach systems programming using Rust.
+- [Scientific Rust](./content/scientific-rust.track.toml) is about using Rust in scientific programming.
+
+*Note: although the outline of the tracks is mostly complete, the tracks may still contain TODOs. You're invited to contribute your own content to fix these!*
+
 ## High-level goals
-Rust 101 aims to provide an open-source course, lectures, tutorials and exercises, that can be used by any higher education institution. In its entirety or by using bits and pieces to create your custom course.
+Rust 101 aims to provide an open-source course, lectures, tutorials and exercises, that can be used by any higher education institution.
+Use one of the pre-defined tracks, or compose your own with the content we provide and your own.
 
 1. Provide a modular, resuable basis for live-taught Rust courses
 2. Provide students with practical, hands-on experience

content/scientific-rust.track.toml

@@ -1,4 +1,4 @@
-name = "Rust for Systems programming"
+name = "Scientific Rust"
 modules = [
     "mods/0-intro/mod.toml",
     "mods/A-foundations/mod.toml",

modmod/README.md

@@ -0,0 +1,79 @@
+# Rust 101 ModMod
+
+`modmod` is a tool that stitches together the Rust 101 content into a collection of exercise scaffolding, the exercise decription book, and Sli.dev slides.
+Provide it with a track definition TOML file, and it will collect everything that's needed to run your custom course.
+
+## Usage
+```txt
+Usage: modmod [OPTIONS] --output <OUTPUT_DIR> <TRACK_TOML_PATH>
+
+Arguments:
+  <TRACK_TOML_PATH>  
+
+Options:
+  -o, --output <OUTPUT_DIR>  The folder the output will be written to
+  -c, --clear                Clear the output folder
+  -h, --help                 Print help
+```
+
+For instance, you can run the following to render the Rust intro track into `./target/course`:
+
+```bash
+cargo run -- -o target/course -c ../content/rust-intro.track.toml
+````
+
+Have a look at file the structure and the TOML files in [content](../content) to get an idea of how the input is structured.
+
+## Output
+
+ModMod outputs a file structure that looks like this:
+
+```txt
+$ tree -L 2
+.
+├── book
+│   ├── book.toml
+│   └── src
+├── exercises
+│   ├── 1-course-introduction
+│   ├── 2-foundations-of-rust
+│   └── 3-crate-engineering
+└── slides
+    ├── 1-introduction.md
+    ├── 2-foundations-of-rust.md
+    ├── 3-crate-engineering.md
+    ├── images
+    └── package.json
+````
+Note that many subfolders were excluded in previous example. You can run `tree` yourself in the course output folder to see the structure deeper down.
+
+The `book` folder contains definition of the MdBook containing the exercise descriptions. You can build it using [MdBook](https://github.com/rust-lang/mdBook):
+```bash
+# install mdbook using Cargo
+cargo install mdbook
+
+# Move to book path
+cd /path/to/course/book
+
+# build the book
+mdbook build
+
+# serve the book
+mdbook serve
+````
+
+The `exercises` folder contains the scaffolding of the included exercises as referred to by the exercise description book.
+The `slides` folder contains a package of the unit slides, which you can render using [Slidev](https://sli.dev).
+```bash
+# Move to slides path
+cd /path/to/course/slides
+
+# Install dependencies
+npm install
+
+# Build the slides of unit 1
+npm build-1
+
+# Render the slides of unit 1
+npm run dev-1
+```