LWN: Comments on "Formatted Rust kernel documentation available"

Tweak it a bit?

Cyberax — Sat, 24 Aug 2024 01:17:20 +0000

A bit of both. It's hard to see the settings icon, it seems to be a part of the search bar. Maybe add a bit of spacing before "?" and the settings button?

The "persistent navigation bar" can probably also be renamed as "side panel".

Tweak it a bit?

notriddle — Sat, 24 Aug 2024 01:02:54 +0000

Is the name of the setting not clear? Or is the settings button itself not easy to recognize?

(I'm trying to come up with a mitigation that doesn't add another button. Lots of people think rustdoc has too many buttons already.)

Tweak it a bit?

Cyberax — Sat, 24 Aug 2024 00:14:24 +0000

> Yes it can. Click the cog wheel button, then check "Hide persistent navigation bar".

OK, thanks! It'd be nice to add a button right on the bar, because these settings and nigh undiscoverable.

Tweak it a bit?

notriddle — Sat, 24 Aug 2024 00:05:01 +0000

> 1. The left panel can't be hidden.

Yes it can. Click the cog wheel button, then check "Hide persistent navigation bar".

> 2. The text does not scale to the full size of the screen.

That sounds easy, until you realize that half of rustdoc's output is hard-wrapped code anyway. It's not worth it.

Tweak it a bit?

khim — Thu, 22 Aug 2024 22:02:35 +0000

You can play similar tricks with Rust documentation, too (only there Hide persistent navigation bar is option in preferences and maximum width requires CSS styles override).

My point wasn't that LWN is badly done, but more of an opposite. Countless web sites use such design. Heck, even such different things as Windows 95 Help system or Chrome/Firefox settings are done in the same fashion. Or, damn, Norton Utilities for DOS (starting from version 4.5? don't remember, but not from version 1, that's for sure). If so many adopt it, then, perhaps, that's what people perceive as “pleasant and useful”, otherwise it wouldn't have survived for so many years!

Alternative would be an admission that all these designers that done so many various web sites (and not just web sites!) with this rough layout approach are all idiots that push things that people hate… or maybe that there are some worldwide conspiracy that makes them do that… and these theories are all very strange and convoluted, it's much easier to believe that something that you, personally, may not like is, in reality, something that other people, mostly, like.

Tweak it a bit?

corbet — Thu, 22 Aug 2024 16:40:48 +0000

Just to add to that: the sidebar disappears when the window gets too narrow, and there is also a preference (Maximum width for handset presentation) that lets you control the value of "too narrow". Set that preference to a suitably large number, and the sitebar will be banished forevermore.

Tweak it a bit?

daroc — Thu, 22 Aug 2024 16:28:13 +0000

In LWN's case, you can customize how the site appears in your preferences. Specifically, you can set the width of the main text element. We don't have a way to hide the sidebar in there, but it does automatically hide itself if the window gets too narrow.

Tweak it a bit?

khim — Thu, 22 Aug 2024 16:24:54 +0000

That's not uncommon complaint: LWN, e.g., have the exact same issues.

I just come to accept that people are different and these two things are, for some reasons, desired by most readers, or else why would they persist for decades?

Tweak it a bit?

Cyberax — Thu, 22 Aug 2024 05:25:43 +0000

A couple of things always bug me:
1. The left panel can't be hidden.
2. The text does not scale to the full size of the screen.

This is extremely cool

Rudd-O — Tue, 20 Aug 2024 17:36:32 +0000

Not only is Rust now solidly beginning to wrap and build on the kernel, this documentation is absolutely delightful to read. Seriously, this beats reading C code by a light year.

I find that quite often perusing this type of documentation (Rustdoc), even if there is exactly zero human readable text, just the structs and traits, is perfectly adequate to use a crate productively. If that is the way kernel docs are going, then I foresee a 10X jump ie kernel programming productivity for those who use these affordances and contribute to make them more extensive.

Sooooooooo nice!

I like this

python — Mon, 19 Aug 2024 21:42:04 +0000

I personally find this really accessible compared to learning the C kernel api.