4 ms·

http://www.cplusplus.com/reference/ http://www.cplusplus.com/reference/ Far far far better documentation. The Rust documentation is a mess and difficult to re

http://www.cplusplus.com/reference/ http://www.cplusplus.com/reference/ Far far far better documentation. The Rust documentation is a mess and difficult to read for many people, but many involved in Rust seem to deny that it is a problem.

steveklabnik 9y ago
Docs team lead here. Specific feedback on improving the output of the docs is absolutely, 100% welcome. Without knowing what "it" is, I can't say if we're "denying that it is a problem." We are constantly tweaking the layout of stuff, and have some larger plans on the way as well.
- lloyd-christmas 9y ago
  For the languages I've used (Node and Python), I'm just comparing the ease of finding documentation on the language homepage. A typical flow is: Homepage > docs > reference/api Node is very straightforward: https://nodejs.org/api/index.html https://nodejs.org/api/index.html Python has a library reference and a language reference: https://docs.python.org/3/library/index.html https://docs.python.org/3/library/index.html https://docs.python.org/3/reference/index.html https://docs.python.org/3/reference/index.html All 3 of these pages are blatantly obvious index pages. For Rust, this is where I assume you're supposed to end up (there are way too many links on the "Documentation" page, I'll address this at the end): https://doc.rust-lang.org/std/index.html https://doc.rust-lang.org/std/index.html You have to navigate/scroll to see the actual list of modules/types/macros or minimize the "about" section. The first thing that I think I should see on an API docs page is an index with maybe a very short blurb/link in regards to the prelude. If the API reference needs a "How to read this documentation" that is long enough to block you from seeing the index itself, something is wrong. Any user that clicks into an API specification either knows how to read it or knows how to click a link that says "about these docs". If they didn't, they would likely be in the "learning" section. Beyond that, the section has a list of 4 links, 3 of which are anchors (that are both out of order and already listed on the left nav) while the prelude link goes to a completely separate page. To address the Documentation landing page, you have "Learning Rust" and "References". Learning Rust > The Rust Programming Language and References > Syntax Index effectively both go to the same page. At the bottom you have a "Project Policies". Are those really part of "Documentation"? I generally think of "language" documentation, not "organization" documentation when I see the header. I would expect a documentation landing page to be a lot more minimal and easier on the eyes, similar to: https://doc.rust-lang.org/nightly/ https://doc.rust-lang.org/nightly/ What that page has in common with almost every other language documentation page that I just visited: Bullet points and/or indentation. EDIT: I should add that I browsed around various language pages while writing this. To add some context for my opinions, I found the Elm docs to be far and away the easiest to navigate excluding the fact that they don't have links to the source code per method. I made it to their API docs without ever hitting an incorrect link. Julia was similar, but I mis-clicked on the manual rather than the standard library because everything is on the same page and neither section collapses.
  - steveklabnik 9y ago
    Thank you! It's a bit late here, so I'm going to bookmark this and get back to it when I can fully appreciate all the detail <3
- SCdF 9y ago
  FWIW I find the book very easy to follow and understand, but the auto-generated docs to be kind of confusing. I think because: a) the general layout feels a bit weird to me. I can't work out which bits are important and which bits aren't. There is no table of contents or similar structure b) as I'm still learning Rust the function signatures are often black magic to me, which adds to the confusion https://doc.rust-lang.org/std/boxed/struct.Box.html https://doc.rust-lang.org/std/boxed/struct.Box.html is a good example. This is a huge page, and it's overwhelming with no table of contents, or without things I probably don't care about collapsed. It is not clear to me how to use Box from this page. Specifically for Box there is a code example on how to create a Box (great) but no indication of how to use one. Turns out you just use it and it works transparently like T would. Unlike a monad like Option or whatever. I don't know if this is obvious is you're an expert looking at the Struct signature at the top, but it's not obvious to me. It's also not obvious from the module documentation: https://doc.rust-lang.org/std/boxed/ https://doc.rust-lang.org/std/boxed/. Then sections are broken down into different implementations against Box. Is that helpful? As a noob I don't know why that matters, I primary want a list of functions that I can interact with. I see a lot of the function signature contains links, specifically to any other struct / trait / whatever. This is really helpful. It would also be great if there was some way of getting up to speed with parts of the structure I don't understand as well, as Rust has that Scala / Haskell trait of crazy complicated function signatures. I realise putting links on all bits is infeasible, so perhaps that is a documentation page itself, similar to how SQL structures are documented: https://www.sqlite.org/lang_select.html https://www.sqlite.org/lang_select.html
  - steveklabnik 9y ago
    Thanks! This is helpful. It’s true that the API docs are mostly written from an “I know Rust” perspective; but some of these kinds of things wouldn’t harm that. > Is that helpful? As a noob I don't know why that matters, I primary want a list of functions Yes, as it lays out the requirements for each one. Not every method is always available; it depends on what’s in the box!
plandis 9y ago
What is explicitly better about it? From glancing it seems similar.
- deleted 9y ago
  [deleted]

steveklabnik 9y ago

Docs team lead here. Specific feedback on improving the output of the docs is absolutely, 100% welcome. Without knowing what "it" is, I can't say if we're "denying that it is a problem." We are constantly tweaking the layout of stuff, and have some larger plans on the way as well.

lloyd-christmas 9y ago
For the languages I've used (Node and Python), I'm just comparing the ease of finding documentation on the language homepage. A typical flow is: Homepage > docs > reference/api Node is very straightforward: https://nodejs.org/api/index.html https://nodejs.org/api/index.html Python has a library reference and a language reference: https://docs.python.org/3/library/index.html https://docs.python.org/3/library/index.html https://docs.python.org/3/reference/index.html https://docs.python.org/3/reference/index.html All 3 of these pages are blatantly obvious index pages. For Rust, this is where I assume you're supposed to end up (there are way too many links on the "Documentation" page, I'll address this at the end): https://doc.rust-lang.org/std/index.html https://doc.rust-lang.org/std/index.html You have to navigate/scroll to see the actual list of modules/types/macros or minimize the "about" section. The first thing that I think I should see on an API docs page is an index with maybe a very short blurb/link in regards to the prelude. If the API reference needs a "How to read this documentation" that is long enough to block you from seeing the index itself, something is wrong. Any user that clicks into an API specification either knows how to read it or knows how to click a link that says "about these docs". If they didn't, they would likely be in the "learning" section. Beyond that, the section has a list of 4 links, 3 of which are anchors (that are both out of order and already listed on the left nav) while the prelude link goes to a completely separate page. To address the Documentation landing page, you have "Learning Rust" and "References". Learning Rust > The Rust Programming Language and References > Syntax Index effectively both go to the same page. At the bottom you have a "Project Policies". Are those really part of "Documentation"? I generally think of "language" documentation, not "organization" documentation when I see the header. I would expect a documentation landing page to be a lot more minimal and easier on the eyes, similar to: https://doc.rust-lang.org/nightly/ https://doc.rust-lang.org/nightly/ What that page has in common with almost every other language documentation page that I just visited: Bullet points and/or indentation. EDIT: I should add that I browsed around various language pages while writing this. To add some context for my opinions, I found the Elm docs to be far and away the easiest to navigate excluding the fact that they don't have links to the source code per method. I made it to their API docs without ever hitting an incorrect link. Julia was similar, but I mis-clicked on the manual rather than the standard library because everything is on the same page and neither section collapses.
- steveklabnik 9y ago
  Thank you! It's a bit late here, so I'm going to bookmark this and get back to it when I can fully appreciate all the detail <3
SCdF 9y ago
FWIW I find the book very easy to follow and understand, but the auto-generated docs to be kind of confusing. I think because: a) the general layout feels a bit weird to me. I can't work out which bits are important and which bits aren't. There is no table of contents or similar structure b) as I'm still learning Rust the function signatures are often black magic to me, which adds to the confusion https://doc.rust-lang.org/std/boxed/struct.Box.html https://doc.rust-lang.org/std/boxed/struct.Box.html is a good example. This is a huge page, and it's overwhelming with no table of contents, or without things I probably don't care about collapsed. It is not clear to me how to use Box from this page. Specifically for Box there is a code example on how to create a Box (great) but no indication of how to use one. Turns out you just use it and it works transparently like T would. Unlike a monad like Option or whatever. I don't know if this is obvious is you're an expert looking at the Struct signature at the top, but it's not obvious to me. It's also not obvious from the module documentation: https://doc.rust-lang.org/std/boxed/ https://doc.rust-lang.org/std/boxed/. Then sections are broken down into different implementations against Box. Is that helpful? As a noob I don't know why that matters, I primary want a list of functions that I can interact with. I see a lot of the function signature contains links, specifically to any other struct / trait / whatever. This is really helpful. It would also be great if there was some way of getting up to speed with parts of the structure I don't understand as well, as Rust has that Scala / Haskell trait of crazy complicated function signatures. I realise putting links on all bits is infeasible, so perhaps that is a documentation page itself, similar to how SQL structures are documented: https://www.sqlite.org/lang_select.html https://www.sqlite.org/lang_select.html
- steveklabnik 9y ago
  Thanks! This is helpful. It’s true that the API docs are mostly written from an “I know Rust” perspective; but some of these kinds of things wouldn’t harm that. > Is that helpful? As a noob I don't know why that matters, I primary want a list of functions Yes, as it lays out the requirements for each one. Not every method is always available; it depends on what’s in the box!

plandis 9y ago

What is explicitly better about it? From glancing it seems similar.

deleted 9y ago
[deleted]