ratatui-book ideas and feedback

[kdheepak]

We intend to follow documentation principles from https://documentation.divio.com/

The tutorials page on there is filled with good advice: https://documentation.divio.com/tutorials.html

From that perspective, I have a feeling we might have to rethink parts of the tutorials, and possibly combine or consolidate some of them. I'm going to list out goals for different sections in a following, and maybe we can talk about the best way to accomplish those goals.

Here's a summary of the current state according to me:

• As a complete newbie to ratatui and rust, the hello world example is good.
• As a beginner to ratatui and fairly new to rust, the counter example is just fine in my opinion.
• As a beginner to ratatui and someone fairly new to rust, the async section is way too much information.
• For someone experienced in rust or programming in general but new to ratatui, the current stop watch example or the JSON editor example is the best place to start in my opinion.
• For someone experienced in rust and experienced in ratatui, the stop watch example has some tips and tricks on using tokio + logging + configuration directories + panic handling etc.

The challenge here is coming up with material for a diverse target audience but also something that flows well in the book. Additionally, at the moment, it is not clear to a reader what the material is going to get them or what is expected of them to know.

So questions I have are:

1. Does anyone have better suggestions for organizing this and presenting this information?
2. Right now, I'm trying to linearly build up complexity but there's complexity in different forms

• in the form of using async,
• in the form of "domain knowledge" (e.g. understanding the stop watch example requires reading through code that is different when understanding the JSON editor example), and how to manage the app state for that domain
• in the form associated with panic handling, logging, etc
• in the form of complicated widgets and fancy UIs (the only thing that's really associated to ratatui)

3. What do people think is most useful to focus on?

[kdheepak]

What do we think about organizing the tutorials this way?

1. Counter App (introduction to ratatui)
   • j and k to increment and decrement the counter and that's it. Has the following 4 subsections:
     • 1 function that does everything
     • multiple functions
     • multiple files (QUESTION: is this even required? most users using rust probably know how to split their code. Is it worth walking through that process? Did people that worked through the tutorial so far find this useful)
     • async version (more simplified that what is currently in there)
2. JSON Editor (basics of a real world application)
   • app with inputs + enum modes + printing result
3. Stop watch (all the bells and whistles of a real world application like logging, key configuration, xdg folders etc)
   • more external dependencies + Async + FPS counter (+ maybe we can render performance optimized? + showcase profiling tools?)

[joshka]

<opinions>

I'd prefer to avoid building something that doesn't have an obvious use like a counter app. It's why I think a stopwatch app is a bit better as a first app. I don't see that ever needing XDG, config, logging, key binding changes, or even async really. It demonstrates: terminal, keys, layout, style, a couple of widgets (table, paragraphs, etc) which seems like the bare minimum.

When you do want to introduce async it provides a good base to start from.

For tutorial about xdg, config and logging you'd want to think about something that someone would naturally want to change the configuration of - configuring themes on the stopwatch might be an idea, but it seems weak and I'm sure there are better ones.

• Multiple files: Ratatui may be the user's first experience with rust. We should suggest creating specific files, but it should not be a specific step (more every step puts stuff where it belongs).

[kdheepak]

I still think a counter app is a good first example just to show the very basics of rust + ratatui. I could be convinced that it doesn't need XDG, config, logging, key binding changes, async etc.

Take https://learn.svelte.dev/tutorial/welcome-to-svelte for example. Their Introduction / Welcome to Svelte is this::

<h1>Welcome!</h1>

Everything in their Introduction section is no more than a few lines of code:

Their first reactive app example is this:

<script>
	let count = 0;

	function increment() {
		count += 1;
	}
</script>

<button on:click={increment}>
	Clicked {count}
	{count === 1 ? 'time' : 'times'}
</button>

vuejs also starts with a counter example:

Superficially it is similar because it a counter app but also conceptually, a counter app is trivial to understand and people can focus on all the other things that they have to do to get started:

<kit.svelte.dev> does start off with a project structure:

I think looking at these tutorials for inspiration, I'm getting some other ideas but to the point of this comment. The first introduction app should not have any more dependencies than absolutely necessary.

[mindoodoo]

General comments

• The tutorials are inconsistent in the way of laying out the code. For example the counter app single function approach (2.2.1) starts by laying out all the code, and then going through it step by step as opposed to 2.2.2 where it goes through the code step by step and then gives the full code at the end. Although this should of course depend a little bit on the tutorial, we could probably make it a little more consistent.
  • Another example would be the json editor tutorial that only gives the full code in the conclusion chapter
• Some notions presented in a noob friendly way could maybe have more external links to articles, tutorials, documentation and what not. Would really help spike the interest of beginners reading the book. Dunno if I make sense here haha.
• The stopwatch app looks awesome, but maybe removing the big code block in favour of simply linking to the code folder might be a bit better ? The code block is really big relative to the explanations provided.
  • Of course an alternative would be to add more explanations to the code, but imho it doesn't really make sense to keep a big code block like this one in the book when a link could suffice.
• Is there any particular reasoning for having the tutorials so soon in the book ? Maybe we could move them a bit further back after we've introduced common concepts and architectures in ratatui. Something like right after section 4.
  • This would be similar ish to what's done in the rust book that introduces the concepts first and then features the first project in section 12.
• Section 3.3. could benefit from a comparison of the different application architectures, as well as potentially something similar to the backend selection flowchart.
  • Would also help to have each architecture consistently present it's pros and cons. From what I've seen only the 3.3.3. Flux Architecture presents pros to it's architecture (no cons though).
• 4.2.2. doesn't mention the stylize trait

Nit picks

• The tip in section 1. might mislead readers to thinking that most widgets require the all-widgets flag
• Would be nice to state that the counter tutorial will present three different ways of writing it in it's introduction (2.2)
• The code examples don't all use the same tab size
• Since 3.3. Application Patterns really only presents architectures, maybe it could be renamed "Application Architectures". Although that depends on wether or not more content will be added there in the near future.

I'll try and open some PRs for some of these comments but don't know how much I'll be able to get done as I'm really busy with classes and my graduation project. The book has come such a long way since it's inception, it's really neat to see !

[mindoodoo]

Something I forgot to mention and which is actually one of the biggest points for me is that I don't feel like there are nearly enough parallels drawn between the tutorials and the applciation architectures that are exposed in section 3.3 (if any). I think it's really important that we be consistent between the application architectures we present to the user, and applying those same architectures within the tutorials as well as stating that clearly.

[mindoodoo]

What do people think is most useful to focus on?

From what I gathered reading the current state of the book, it seems like it is still relatively unclear exactly who is our target audience. On the one hand, the book covers very basic things such as basic cargo commands and crate adding in the hello world tutorial, but on the other it also covers async in a very brief manner.

It seems like the book might be targeting a slightly too broad audience. I feel like some of the most newbie friendly stuff such as cargo commands and what not could be dropped in favour of linking to other more general rust tutorials or the rust book.

It would also be great to state clearly the expected knowledge for each tutorial at the beginning as well as linking to external stuff to gain that knowledge. This would allow us to keep some of the more complexe tutorials such as the async one while at the same time not confusing users that are really new to rust and that have been going through the book in a sequential manner.