Missing Section: What is Tokio?

[rylev]

There's a need for an introduction to what Tokio is beyond the short synopsis on tokio.rs. The description should be without buzz-words or jargon and it should explain what Tokio is actually for.

This section should cover the following topics:

• Blocking vs non-blocking and Async vs. non-async
• The fact that the Rust std lib only supports blocking APIs for I/O
• Short examples of what Tokio allows: multiple client HTTP requests on a single thread, timers that don't require blocking or spin locking a thread, etc.

A lot of this is covered in the runtime model section, but the user has already had to go through the hello world example before getting there.

[carllerche]

There is a bit of this in the Overview section. Do you have further feedback based on that?

Renaming it to "What is Tokio?" or something like that would be an improvement. Overview is vague.

[rylev]

First, the "Get Started" link on the tokio.rs main page goes to the "Getting Started -> Hello world" section. I completely missed the overview section for this reason. I suggest changing that.

Second, the overview is fairly advanced. As a beginner I might read "event-driven, non-blocking I/O platform" and have no idea what it means. Additionally, the mentions of "epoll, kqueue, IOCP" and "work-stealing based task scheduler" might scare me off as well.

This seems like a classic issue with documentation. For the advanced user this overview is perfect. It gives a very clear idea of what Tokio is. However, it fails to answer the question of "what do I use Tokio for?". Advanced users are able to easily piece this together, but less advanced users might not be able to.

A paragraph or two explaining with as little jargon as possible what Tokio is used for would be helpful.

[carllerche]

Yeah, the "overview" is mostly to expand on the marketing topics on the homepage.