Clarify ordering of log levels in the docs

[DevJac]

It was not clear whether error or trace was the maximum log level.
The docs said "error! represents the highest-priority log messages and trace! the lowest".
Yet, set_max_level regards Trace to be the maximum level.

I attempted to clarify this by avoiding the terms "high" and "low" in the docs except for where
they are applicable to the Rust order as defined in Ord.

I spent about 30 minutes being confused by this. It seemed to me that set_max_level would be used to filter errors and warnings while emitting debug messages, which confused me.

I was going to create an issue first, but decided I would update the docs myself as an initial proposal of how to improve them, so I have created this PR instead.

[KodrAus]

Thanks @DevJac!

Hmm, I guess neither description is really capturing what log levels are all about. I think priority is probably a more accurate end-user description because info logs aren't necessarily less important than warnings or errors, they're just produced by different events occurring in your system. You probably care more about observing errors because they mean something is broken.

I guess what we're really trying to say in this section is that levels give you a hierarchy to tune the amount of noise being produced, with the assumption that you'll log fewer errors than warnings than infos than debugs than traces.

Perhaps we could avoid relating the log levels by priority or importance and just talk about ordering in terms of max levels so we say error represents the maximum log level that implies all the others and then list each level in order so it's clearer how they're ordered?

[DevJac]

Thanks for your thoughts @KodrAus.

I think priority is probably a more accurate end-user description because info logs aren't necessarily less important than warnings or errors

I agree that "priority" is a better description than "important". However, I do not like the word "highest" in the phrase "highest priority", because [in my opinion] "highest" and "maximum" are synonyms. I get confused reading that error is both "highest" and "minimum" - it seems contradictory to me, like saying "error is maximum and minimum".

I guess what we're really trying to say in this section is that levels give you a hierarchy to tune the amount of noise being produced, with the assumption that you'll log fewer errors than warnings than infos than debugs than traces.

I agree, and this was always clear to me having used logging libraries in other languages. My only point of confusion was what argument I should give to set_max_level.

Perhaps we could avoid relating the log levels by priority or importance and just talk about...

I think it will be difficult to talk about the log levels naturally without using min/max or some synonyms. For example, you said (emphasis mine)...

error represents the maximum log level

... but, (I gotcha 😉 ) error is, technically, the minimum log level. This is a great example of how difficult this is to talk about accurately.

One possible solution is to rename set_max_level to set_min_level. That would seem more natural to me. I can understand how others would see it differently though, and I don't know if it's worth changing.

Or we could just included a note like...

Note that Trace is the maximum level, because it provides the maximum amount of detail in the emitted logs.

... on set_max_level, as I have done. I would be 100% satisfied with only that note; that note would have saved me some time when I was first using log. We don't need to change any other wording.

What do you think?

[KodrAus]

It is all very tangled, isn't it. I think your last snippet on Trace though is very clear and understandable and I think that would be a great clarification.

[DevJac]

Ok. I've reverted most of my wording changes, leaving only the note on set_max_level. Thanks again for your input on this. I think we are in agreement now?

[KodrAus]

Sorry for never coming back to this! This looks good to me 🙇