Front-end design questions

[steveklabnik]

While many people love rustdoc's look and feel today, it was never really "designed".

Should we tweak it? In what way? How much?

These are all open questions.

[notriddle]

Throwing out exdoc as something worth comparing to:

• The tree view in exdoc's sidebar makes browsing easier, since it's sticky, allows you to browse around other modules without actually leaving the page, and it goes all the way down to individual functions. Compare the sidebar on the docs for Elixir.Map.delete/2 with the docs for std::collections::HashMap::remove.
• Pages: pieces of documentation that aren't actually connected to language items. You list them in your ~~Cargo.toml~~ mix.exs, and they end up in the documentation. I know I'm not the first person to ask for this.
• You can configure a particular page for it to use as home, instead of sticking all your docs in the top of your root module. This also allows you to just use your README as your doc home.

Just don't copy the PAGES/MODULES/EXCEPTIONS/PROTOCOLS thing. I have no idea why they thought that 1/3 of the sidebar should be taken up by that unintuitive tab widget.

[SamWhited]

I have a slightly vague design decision that I'd like to bring up: right now docs made with rustdoc are very "complex" in the sense that there is a sidebar and numerous levels of documentation (you can drill down into crates and modules and structs and enums, etc.) and you can't always see all those levels (eg. if you're in a crate with one module, that's already selected, but then you might have to scroll to the bottom of the rigth page to find out what's actually in that module), the navigation in the left bar changes between pages, etc.

It would be nice if the whole thing could be simplified drastically. Making docs simple (in terms of design and navigation) makes them easier to read, this is something I think we could learn a lot from godoc on, for example, compare how easy it is to find everything in this set of docs vs. a similar Rust package when the docs are very clean and simple and have an index at the top:

• Godoc: https://godoc.org/mellium.im/xmpp/jid
• Rustdoc: https://docs.rs/xmpp-addr/0.11.1/xmpp_addr/

I think the things that make the Go docs a lot easier to find anything in for me are three fold:

• Single page: I can Ctrl+F over the entire docs and find all references to a function, and search engines only have one thing to index, so I don't end up finding 10 different pages to click through that way (although this would probably be different for books, which is an additional case for rustdoc you mentioned)
• API overview in the form of an index (I can see the entire API, get a vague idea of how it fits together, and then jump straight to a particular part of it)
• "simple" layout (this ones a bit vague, but it's just not as cluttered; there aren't multiple bars presenting information to me, there aren't buttons all over the place, there isn't a sidebar that doesn't actually have much of anything in it unless you're working on a huge package, etc.)

[Alex-PK]

One thing I really dislike about the current docs is the low discoverability of functions.

Take the Vec page, for example: https://doc.rust-lang.org/std/vec/struct.Vec.html Try to collapse all to have an overview of the functions.

The dominant part is formed by trait names, generics, lifetimes, and the functions signatures are barely readable. Also, from is defined at least 10 times, so are eq, ne, etc. I understand why, but it makes the docs unreadable.

What I am proposing is to make the function name dominant, and only list it once, maybe skipping the types, and show them in a smaller form in a side box.

Something like:

<h1>fn index(&self, index)</h1>
<aside><ul>
 <li>
    <h2>fn index(&self, index: usize) -> &T</span>
    <h3>impl<T> Index<usize> for Vec<T> type Output = T</h3>
 </li>
...
</ul></aside>
<main>
  Function description
</main>

(h1, h2, h3 just to highlight the importance, not the style)

This would allow to have a quick overview of what's available in a struct/trait and dig deeper into implementation details if needed. Take the PHP manual, for example: http://php.net/manual/en/class.datetime.php (There are no generics in PHP yet, so it's much simpler. That's why I suggest to hide the types in the "title")

[ehuss]

Something I would like to see is to have methods organized into sections. Having a large list of methods in some arbitrary sort order (alphabetical or source order) makes it difficult for me to find things, particularly if you are exploring what an item is capable of.

Some examples:

• Apple does this with most of their API documentation (UIView example).
• Doxygen has Member Grouping to accomplish this.

I went through and did this for the large structs in std and it really helps me find what I need. Not sure if this idea is more appropriate for a separate issue, since it extends beyond just styling.

[ghost]

I think it'd be nice to have a switch that changes the colour palette, e.g. white, sepia and black. That setting could be stored using localStorage.

Similar option is already present in the book.

[huwwynnjones]

Racket docs are very nice:

https://docs.racket-lang.org/guide/index.html