rustdoc: Style Improvements?

[exzachlyvv]

As a newcomer to Rust, the docs.rs content is 💯 but the UI is lacking in my opinion. Let's make the documentation easier to digest! :D

Here are a few of the improvements I'm thinking of:

1. Font improvement? The current font reminds me of Time New Roman, which is quite dated. 2 of my favorites are Nunito and Montserrat.
2. Improved line and letter spacing for readability.
3. Improvements around inline code markdown UI.
4. Plenty more we could do :p
5. I came over from Laravel. Their documentation is gorgeous. I see no reason that docs.rs can't match that.

I would be happy to submit a PR for this. Just want to check on the current state before doing so :)

[jyn514]

@exzachlyvv thanks for thinking about this! Docs.rs actually has its documentation generated by a tool called rustdoc, so I'll move this over the right repository. If you'd like to make some styling changes take a look at src/librustdoc/html/static. Feel free to ask for help on https://rust-lang.zulipchat.com/#narrow/stream/266220-rustdoc if you get stuck :)

[jyn514]

cc @jsha

[willcrichton]

My 2c -- I think UI improvements to Rustdoc should be rooted in ease of use, not quality of aesthetic. I agree that the Laravel docs look quite nice, but I personally find their font harder to read than Source Serif Pro.

IMO, documentation should fundamentally be utilitarian, not beautiful. Which isn't to say there aren't changes that both make the documentation easier to use AND prettier to look at. But the grounding question should always be things like, does this change reduce the amount of time it takes for user X to solve problem Y?

[willcrichton]

Also fwiw, the Laravel automatically-generated documentation (which is the main rustdoc use case, as opposed to mdbook-style guides) looks very different.

[jsha]

Hi @exzachlyvv ! Welcome to Rust, and welcome to rustdoc. You may be interested in this issue, which recommends some style changes based on accessibility. In particular I notice that both of the fonts you recommend are sans-serif fonts, and the issue I linked (#59829) also recommends sans-serif:

Beside the visual clutter, there are a few other aspects of the default Rust docs styles which can cause problems for people with dyslexia:
It uses serif fonts for the body text, while sans serif fonts are generally preferred for readability

I think that's a pretty strong reason! It would be useful to find some citations for it, though. Is that something you're interested in doing?

Also, if we decide to move to a sans-serif font for most documentation text, one option is Fira Sans, which we already use for headings. I'm not well equipped to evaluate Fira Sans vs Nunito or Montserrat, but if you could provide some description of why the latter two might be more readable, that would be awesome.

[exzachlyvv]

That issue does a much better job of describing my feelings :D I'll follow that.

Thanks for the responses!! I'm loving Rust 😎