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.

[QuietMisdreavus]

Claiming this one. I'd like to get this sorted somehow during this release cycle. That may involve folding it into "The Rustdoc Book" (#42322) but I'd like to get better "this is the layout of rustdoc output" docs somewhere.

[QuietMisdreavus]

Update: I started writing a "Rustdoc Field Guide" that would spell out some tips and tricks, but i got halfway through before moving on to other projects. I wrote it as a set of crate docs, with the intent of letting the user try out all the features as they read about them. This does pose a question about integrating into other "books", though, since API docs are difficult to fully integrate into mdbook-generated guides like The Rustboc Book. Regardless, i wanted to bring up the partial work i'd done here.

[steveklabnik]

An old reddit thread: https://www.reddit.com/r/rust/comments/36f94o/how_do_i_read_the_api_docs/?st=j7kwlbm2&sh=20a2081c

[steveklabnik]

Triage: we are still not sure what this would even look like, so removing p-high. Nobody is actively working on this that I'm aware of, and if we don't sort out a plan, I intend to just close.

[DevQps]

@steveklabnik I personally think the docs are already quite intuitive as they are. I never had problems understanding the content displayed or where to find certain content. Since the module level documentation is often quite good I think that just a handful of people are not able to find what they are looking for, but of course, that is just a guess (can't look into others people's heads).

I just saw that the std main page contains two sections "How to read this documentation?" and "What is in the Standard Library documentation?" which already does quite a good job in my opinion! The only things that are currently not documented (for as far as I know) is what "Trait Implementations", "Auto Trait Implementations" and "Blanket Implementations" are. But I wonder if it wouldn't be a bit too overkill to document what those are on the main page of std. I would suspect that it would scare/off-track of starters more then it would actually help them

I believe it's best to close this issue and focus on making std as accessible and intuitive as possible. But that's just my opinion of course!

[steveklabnik]

Yep, I think I agree. If anyone has a concrete plan, please open a new issue with one!