docs: consider merging repo root readme and tracing crate's readme

[hawkw]

Feature Request

Crates

• tracing

Motivation

Currently, the top-level introductory documentation for using tracing exists in three separate places:

1. the repository's top-level README file
2. the tracing crate's README file (which is rendered on crates.io and docs.rs)
3. the tracing crate's lib.rs docs (also rendered on docs.rs)

This means that there are three separate places where we put the introductory documentation. The lib.rs docs and the tracing crate's README are (theoretically) duplicates of each other and are kept in sync. However, the repository root README contains separate documentation from the tracing README and lib.rs docs, such as links to external resources, etc, and doesn't contain most of the examples.

This is...not good. Docs changes may potentially have to touch three different files, making it hard to keep the documentation in sync. It's hard to know where to put new documentation. And, docs in the repository root README, which theoretically should be the first thing that everyone sees, are not very discoverable for users browsing on crates.io or docs.rs.

Proposal

I think we should combine the root README and tracing README into one file in the repo root, and set the readme key in tracing's Cargo.toml to

readme = "../README.md"

This way, the root readme of the repository will also be rendered on crates.io and docs.rs.

When combining these two readme files, the result will likely be quite lengthy. Therefore, we may also want to think about moving some of the more detailed docs and examples out of the root readme to other locations, and linking to them. Then, we will also want to keep this change synchronized with the lib.rs docs.

I also still think that we should add a table of contents (see #516).

Alternatives

• Just leave everything as is.

• There's been some discussion about including the contents of the README as the lib.rs docs, so that we don't have to keep everything in sync between those two files.

  However, my understanding is that currently, if we want to do this, we need to either use unstable Rust features, pick up an external dependency just for rendering the documentation, or both. Also, it's harder to test the examples in the readme when doing this, and it would change the lib.rs links from relative URIs to absolute URIs, which would mess up the locally rendered docs.

  Therefore, I don't think that this is currently a good idea. But, if it becomes possible to do this just using RustDoc on stable, rather than requiring an external crate or nightly feature, it could be worth looking into in the future.

• We could move a lot of this content from the READMEs and lib.rs to tutorial pages on the Tokio website. This is something I'd like us to have eventually (see docs: Long-form tutorials/docs on tokio.rs #224). However, I don't think we should just remove everything in favour of putting it on tokio.rs, as this may be less discoverable for users whose documentation entry point is crates.io or docs.rs. Instead, I think we should have tutorials that walk through different tasks on tokio.rs, and reference those in the library documentation.

[hawkw]

cc @yaahc @davidbarsky @LucioFranco who undoubtedly have opinions.