Tutorial on how to read the standard library documentation on API docs homepage

[carols10cents]

Moved here from rust-lang/book#477, cc @redactedscribe, who said:

After a quick search, I did not find anything specifically talking about how to actually read/use Rust's standard library documentation. Making sense of programming documentation was not a skill I already possessed though it did eventually become clearer the more I had to refer to it.

Seeing as the documentation style is something that is standardised and used by almost all libraries, perhaps there should be some example in the book where a problem is solved via working with what the documentation informs us about at each stage of the problem.

I think a tutorial that walks through using the docs to solve the problem is a great idea that would be better suited for the std lib's homepage at https://doc.rust-lang.org/stable/std/index.html. There's a small section on "how to read this documentation", but it could be improved with a concrete example :)

cc @steveklabnik

[steveklabnik]

Nominating to discuss at a future docs team meeting; I'd like to figure out a plan before sending in a PR here.

[frewsxcv]

I think it might be helpful to identify how people have encountered difficulties when reading the standard library documentation. I read the associated original issue but am unsure how to effectively resolve their issues. Would it be helpful to ping that user and ask how they stumbled when reading the docs?

[ScottAbbey]

I think it might be helpful to identify how people have encountered difficulties when reading the standard library documentation.

I'll try!

Let's rewind the clock a few weeks for an example of how I tried to use the Rust documentation.

---

I didn't know much about Rust (still don't! pardon any poor language choices here). I wanted to find information about the function as_bytes which I encountered being called on what appeared to be a string while reading some Rust code.

1. I went to doc.rust-lang.org, paused a bit looking at the choices (this step is already improved in nightly!) to find the right one, clicked for the API documentation.

2. I typed as_bytes into the search bar, pressed enter

3. Results looked like this:

   std::os::unix::ffi::OsStrExt::as_bytes  Gets the underlying byte view of the [`OsStr`] slice. 
   str::as_bytes                           Converts a string slice to a byte slice. 
   std::ffi::CString::as_bytes             Returns the contents of this `CString` as a slice of bytes. 
   std::string::FromUtf8Error::as_bytes    Returns a slice of [`u8`]s bytes that were attempted to convert to a `String`. 
   std::string::String::as_bytes           Returns a byte slice of this `String`'s contents. 
   std::ffi::OsStr::as_bytes
   

   I ended up picking the 2nd one. I'm not sure if the std::string::String::as_bytes one was the one I really wanted or not, but I didn't even notice it on the first attempt anyway.

4. Clicking took me to:

   fn as_bytes(&self) -> &[u8]
           Converts a string slice to a byte slice.
   Examples
           Basic usage:
               let bytes = "bors".as_bytes();
               assert_eq!(b"bors", bytes);
   

   Now from the method signature it seemed like this would be giving me something like [100, 101, 102], since I guessed &[u8] meant something along the lines of "a slice of numbers", but I was still not exactly sure what "converts" means (did it have to copy something? did the type magically just change?). I'm also a little confused because the assert_eq line compares this result to b"bors", which I don't yet recognize.

5. I decided to try to figure out what b"bors" was. First I tried typing b" into the search bar. No luck there. Next, I tried to consult The Book. Since I'm hip and cool I checked out the second edition. In order to be able to search it, I pressed the Print button and closed the printer dialog. A quick CTRL+F for b" reveals...nothing! Darn. But b' did have a result. Hmm.

6. I flipped instead to the print layout link of the first edition and tried CTRL+F for b" again. Finally, under Other Syntax I found that this is called a "byte string literal" and it comes with a link to the Reference.

7. I try to read the description of a byte string literal in the Reference, but it's not quite written at the "hey, what is this" level. Eventually I have a good idea what this is.

---

From this experience, I can identify a couple specific spots where things weren't quite ideal:

1. It was really quite difficult to find the name and references for the "byte string literal" syntax after noticing it in the example
2. I wasn't sure which item to select in the search results since there were at least 5 of them.
3. If "converts" as used here has a standard meaning, it would be nice if there was a prominently linked glossary of what specific terms mean in documentation. Kind of like how (IETF) RFC 2119 defines stuff like "MUST" and "SHOULD". If it doesn't have a specific meaning, I'd love to see a better explanation of what the actual behavior here is like.

[steveklabnik]

I didn't know much about Rust (still don't! pardon any poor language choices here).

Don't worry about it; that makes this more helpful, not less!

[QuietMisdreavus]

Some elements I remember people being surprised at is how the types used when rustdoc renders function signatures, struct layouts, etc, are actually hyperlinks to the type itself, and how they have hover text to show the full path. (This comes in handy when disambiguating result::Result from io::Result, which is where this always comes up.) Other tips like the "collapse all" and "view source" links at the top of each page are also what I have in mind.

[steveklabnik]

removing the nominated tag; p-medium means we'll get to it, and we can figure out the plan then.