This is super interesting. Regarding the lack of error handling docs, I’d been meaning to translate @burntsushi’s epic error handling set into a series of rustbyexample examples but I haven’t gotten to it yet (aside from @steveklabnik planning to import them into the regular docs sometime).
Regarding crate library docs, it’s tricky. Even crates which seem to have good examples such as regex with extensive docs on the front page lack structure aside from the what the library provides with sub-headers. For example, every wikipedia page in existence has a table of contents but regex does not. For something complicated, it’s nice to get an overview but that’s tricky with the docs.
One thing that could be done is have library authors create dummy modules strictly for dividing up complex topics into simpler topics (I’ve never seen anyone do it though)? For regex it would be useful to be able to click and go directly to say “repetition” as opposed to say “capturing” sections.
Aside from that, browsing an unknown lib is tricky. The most relevant post I’ve seen regarding that is this reddit post (maybe it’d be useful to people). It also has listed an example of how someone might browse an unknown library (it basically is almost like clicking things at random until you get a feel for it. Hardly great I guess).
I’d be super interested in seeing how the lib docs might be streamlined for the future. Really useful stuff.
[EDIT] Not suggesting dummy docs should be used, though with better support (maybe from the doc generator), more structured docs might be easier.
