Join GitHub today
Having a section on "gotchas" or trouble shooting will be important. Most issues people run into with Tokio probably come down to 3-5 different problems. Having go-to explanations of these will help.
One specific set of gotchas around Tokio is the use of impl Future and lifetimes. There are issues with the borrow checker that users who have written a fair amount of Rust may encounter for the first time when using Futures. Having a section that talks through some subtleties even if they aren't really specific to Tokio would be good.
In this vein:
Generally, it would be good to have a section like this organized by what issue you might be seeing and what some likely causes are, for example "a stream combinator executes once and then hangs", or "the future stops and the RUST_LOG=trace shows an event added to the tokio loop".