docs: Tutorial falls apart in the "channels" section

[theogravity]

I was following the tutorial well until I hit the "channels" section. Unlike the previous sections, I'm not exactly sure what file(s) I should be modifying / creating, or where the modifications should be placed. It really starts to become noticeable once I get to the "Spawn manager task" subsection, where I'm not quite sure I should be placing the manager code.

It feels more like a set of examples than a tutorial at this point.

[carllerche]

That is good feedback. You aren't entirely wrong. I think towards the second half, it is more about providing the necessary context to understand the mini-redis code base. One reason for this is that I want to avoid having a to explain adding a bunch of boilerplate. Thoughts?

[theogravity]

Sorry for the delay in responding (health issues). I'm not sure if it is possible, but I would take the Rust documentation as an example. The way their embedded code works is that it is able to display snippets but you still have the option to see the code in its entirety.

Maybe having an example repository (if it exists, I definitely missed it) that reflects the tutorial would also help.

[Darksonn]

The code from the chapters can be found in the tutorial-code folder. And of course a lot of the code is inspired by the mini-redis codebase.

[Keksoj]

After struggling a bit through the tutorial, I agree whit @theogravity .

The learning flow

Let me explain from my own learning experience. I like to type code in order to learn. So I follow:

• Hello Tokio: Everything is explained to make a simple client code, from cargo new to running the code with mini-redis-server. Perfect.
• Spawning: the simple client code is put into examples/hello-redis.rs and the page starts instructions to build a server. But hey, so far so good.
• Shared state: Further work on the server, the best part of the tutorial
• Channels: Wait what? Where shall I write my code? Where is this main()? Oh wait we're making a client here… let's scroll back up… "concurrency with Tokio, let's apply this on the client side". Got it. So I take a while to check back on the previous pages, and I organize my code like so:

my-tokio-tutorial-directory/
├── tutorial_client   (with channels)
└── tutorial_server  (with Spawning and shared State)
    └── examples  (the first simple client)

Weirdly, the examples folder of the server contains a client example, as instructed in Spawning. But hey, I launch cargo run in both directories and it works.

• I/O: By now I understand I'm on my own so I just read the whole page to see where it's going, and I run cargo new echo-server and I follow the code.
• Framing: Wait, those code snippets look very juicy but there's no main() anywhere? What if I want to play with it? Am I just supposed to copy code that won't be used and think "Mmh, interesting" ?
• Async in Depth: So there's a main() again here? Should I run a cargo new? By the time the tutorial says "let's implement our own minimal version of Tokio!" I am lost entirely. Should I have copied those Frames somewhere after all?

Suggestions

I am a simple man. I see bash commands, I copy them. We need waaaayyyyy more instructions on organizing the code user-side.

I suggest more verbose explanations of the like:

On this I/O page, we will build a super simple mini-redis server that echoes requests. Go back to the root directory, run cargo new echo-server and copy the same dependencies we used before in Cargo.toml.

The list of missing instructions:

• Channels: cd .. && cargo new tutorial-client plus Cargo.toml instructions and cargo run. Basically all of cargo.
• I/O: same, cargo instructions

Now about Framing. I know it's not writen at all but a cargo new and a main() to play with those frames would be very nice.

[Keksoj]

Since MR #565 the Channels and I/O pages are less confusing, but there still should be a mention somewhere that goes like:

From here on, this is less of a tutorial and more of a presentation of what is at stake for building a redis-like asynchronous library. Don't try to copy the code.

Or, way better (but way longer to write), an actual follow-up tutorial on how to build mini-redis, almost from scratch. The boilerplate could be escaped with mentions like "make this file, go to this link and copy everything in the file and don't worry too much".

[pjhades]

I've been following the tutorial and have similar experience.

In addition, as a reader/learner, after reading the Setup section, I thought mini-redis would be used as an example throughout the entire tutorial. But starting from the Channel or I/O section, I realized that I had to switch back and forth between mini-redis and some other independent examples, without being explicitly reminded. Maybe this only happened to me, but it feels a bit confusing, like in a game, a side quest suddenly begins, leaving the player wondering how it relates with the main storyline.

Edit: The Async in Depth section seems to be repeating what is covered by the async book.