Improve README for first time users

[bz2]

Motivation

The documentation nearly put me off trying to use tracing at all. It looks hard to set up and use, and the two problems I first ran into (needing to output to stderr, and instrumenting a function with a non-formattable arg) were not easy to find the right solutions for.

Solution

This change rearranges the README a little to emphasise solutions, rather than problems and extra details a first time user probably doesn't need to care about yet.

• Start with the simple way of setting up a subscriber rather than diving into the complex ways.
• Show the preferred method of instrumenting async code before explaining why it is more complex and how it's implemented.
• Remove yak credit. Does anyone care?

[hawkw]

cc @davidbarsky and @yaahc, who almost certainly have docs opinions.

[hawkw]

Thanks for working on the docs, it's much appreciated! I had a few thoughts that I commented on inline.

A lot of the same examples are reproduced in the tracing crate's README (https://github.com/tokio-rs/tracing/tree/master/tracing#usage), since that's what's rendered on the crate's crates.io page. Once we finalize the changes to the repository README, we ought to try to ensure the relevant changes are reflected there as well.

[hawkw]

And then maybe put the example with the instrument combinator here as well, before discussing the reasons for this?

[bz2]

This was an awkward join between the examples still. I've reworked the language here but left the motivation in the middle, as it helps understand the combinator (though you can arrive here without really having taken in what a span is yet).

[hawkw]

I think we should at least discuss the existence of set_global_default and what it does before this warning. If the first example is changed to show tracing_subscriber::init, then users will read this note before even knowing that there is a function called set_global_default.

Perhaps another example after the first one, explaining that tracing_subscriber::init() uses set_global_default, the generalized way of setting a global default subscriber?

[bz2]

Added some better joining language between the examples to address this. I think one simple example and one complex example is enough?

[yaahc]

I think this is a great idea. I don't have any comments on the particular changes being made but I think I'll follow the example set here and make the same changes to tracing-error to prioritize examples about setup over examples about advanced usage.

My one comment is that I think should be applied to more than just README.md files. I almost never go to the readme first, I usually just type docs.rs/tracing into the url bar and go straight to the docs, so I'd like to see changes like these made to the core docs on the lib.rs file. I think much of the docs on the main page could be moved to a guide similar to SNAFU's docs, and leave the main page to examples of setup and simple usage along with links to relevant crates and whatnot.

[hawkw]

@yaac

I think much of the docs on the main page could be moved to a guide similar to SNAFU's docs, and leave the main page to examples of setup and simple usage along with links to relevant crates and whatnot.

The new version of tokio.rs is going live pretty soon, and will have a tracing section, so that's probably a good home for long-form guides and tutorials. It's mostly usage examples and related crates now

Also, I think the lib.rs docs have gotten a bit more concise recently — in the last couple of releases I think a lot of the more detailed documentation has moved to the span and eventmodules, IIRC.

[bz2]

@yaahc @hawkw Thanks for the reviews! I'll reply to a few specifics inline and make updates.

[hawkw]

@davidbarsky have you had a chance to give this a skim yet?

[hawkw]

I was hoping to get @davidbarsky to give this a skim, but I think it's fine to merge as-is. We can always make more docs improvements in a follow-up.

[davidbarsky]

I haven't had the time; feel free to merge.

[bz2]

@hawkw Thanks! I see from #808 that the future is changing, so lets let that resolve and maybe do another pass over the async bit before propagating to more bits of docs?