Rustdoc (HTML) roles and priority of constituents

rustdoc-html-user-roles.md

Introduction

Note: this is not a policy doc. At least, not yet.

This is a pile of notes that should probably be integrated into the rustc-dev-guide at some point. These roles, at least for me, inform where and how I've designed features and pages in rustdoc.

With these roles written down, I'm going to try to avoid referring to a "rustdoc user" most of the time, because that's not usually specific enough. Rustdoc has three interfaces, with three different audiences, who, sometimes, overlap.

Role	User interface	Config interface	Brute force interface
Author	Doc comments and source code, rustdoc/clippy lints	#[doc] attributes	Raw HTML in doc comments
Publisher	cargo doc, cargo rustdoc, rustdoc CLI	Command line parameters	Patching HTML after running rustdoc
Reader	Web browser, cargo doc --open	Settings popover	Browser extensions, userscripts/userstyles, patching HTML after running rustdoc or downloading a zipball from docs.rs

The crate documentation author

Sometimes they're simply called the "crate author," the "author," or, as a metonym, the "crate." This is the role that writes doc comments, markdown files, and sometimes Rust source code that rustdoc reads.

The structure of a crate's code and the organizational divide between crates is reflected directly in Rustdoc's output, because different crates are, organizationally, written by different authors. It's important that the reader know who's writing.

Configuration knobs are exposed to authors mostly through #[doc] attributes embedded in Rust code. In the future, Cargo.toml or Rustdoc.toml may expose more documentation-related features, and would also be targetted at authors. These settings should be designed to let them change their own docs without changing their sibling crates'.

To best serve the needs of authors, we should

• Provide opportunities for them to leverage their deep knowledge of their own code.
• Make it easy for them to tell what rustdoc "believes," to fix it if it's wrong, and to prevent rustdoc from believing wrong things in the first place.
• Lean on knowledge that crate authors already have about Rust, Markdown, and HTML. Rustdoc is probably not the only documentation generator that crate authors have ever used.

The documentation publisher

This is the role that's not talked about enough, but there are plenty of groups I can name who fit this role better than any other:

• Servo publishes docs for both themselves and their dependencies
• stdrs.dev publishes the standard library docs with private items included
• Many crates, like gtk-rs and rocket, self-publish ("self-publish" means you publish docs that you also wrote)
• docs.rs is probably the largest crate doc publisher

I suppose the main reason they aren't talked about as a distinct entity is that they usually overlap with the other two roles. A reader who uses cargo rustdoc --open has access to all the publisher-facing goodies, and most other publishers are affiliated with crate authors (even Servo, who publishes docs for crates they did not write, is mostly a doc authoring organization who takes on publishing as a side gig). And docs.rs has such close ties to the Rustdoc team itself that we frequently cater to their needs specifically.

But even when the publisher is in the same umbrella org as the author and reader, they aren't necessarily the same people, and the skillset is not the same either. We should try to design rustdoc to help them work together without accidentally stepping on each others' toes.

Because the publisher has the opportunity to simply patch the HTML before hosting it, they always have higher priority than doc authors. We should provide better ways to accomplish their goals without as much risk of subtly breaking things.

To best serve the needs of publishers, we should

• Provide opportunities for them to leverage their deep knowledge of web publishing and hosting infrastructure. Publishers should be the ones in control of where and how things are hosted, not authors.
• Produce minimal, stand-alone HTML output that doesn't place special requirements on how it's hosted.
  • If I run cargo doc --open, I should be able to take the resulting docs into a dead spot and read them without Internet.
• Help docs from different authors play nicely in a single workspace.
• Make it easy to fit Rustdoc output into a larger, pre-existing information architecture. Rustdoc is probably not the only SSG¹ they have to deal with.

The reader

The reader is potentially very ignorant. That's why they're reading docs, after all. While advanced features are welcome, you shouldn't need documentation for your documentation that you have to read while you read. They might know what they're looking for, but rustdoc should be prepared for people who don't.

They also have the highest priority of constituency in HTML, the system that rustdoc uses by default to present docs. They're at the end of the pipeline, so any changes they make will be the last changes that get made. If the incentives are well-adjusted, publishers and authors are trying to cater to the needs of readers, though they might have ideas about what that means that are at odds with the actual readers'.

To best serve the needs of readers, we should

• Plan a learning curve. Advanced users should be able to quickly track down information that they already know about, but new users shouldn't be overwhelmed with a bunch of extra information that they don't understand.
• Follow industry and internal conventions.
• Avoid saying stuff that's contradictory, confusing, or not true.
• Produce HTML that plays nicely with tools like Reader Mode, general-purpose search engines, and a11y tools that aren't designed with Rustdoc in mind. Rustdoc is probably not the only web page they're using.

Okay, but where are we failing these users?

The value of classifying these things by audience is that it informs how it should be exposed: a feature that publishers want should be exposed through the CLI, not source code attributes, and a feature that readers want should be in the frontend JS.

Most issues represent a failure for at least one of these groups, but just to give some examples.

Authors

• rust-lang/rust#112379: Authors can't write docs on some items.
• rust-lang/rust#101337: Authors can't easily communicate information from code to readers in convenient way.
• rust-lang/rust#16300: No support for $\LaTeX$ math. Because the feature isn't here, doc authors add inline JS and take control of hosting static assets away from the publisher.
• rust-lang/rust#66249: Poor support for standalone pages (what ExDoc call "extras"). Because the feature isn't there, doc authors use modules for this, which means rustdoc presents non-existent modules to the reader.

Publishers

• rust-lang/rust#86715: docs.rs wants to split crates into separate workspaces while still affording a search interface that feels unified. gtk-rs wants to be able to delegate all dependencies they do not own to docs.rs. Because the feature isn't there, it's annoying to search the docs if you don't run cargo doc --open locally.
• rust-lang/docs.rs#2196: Transitive dependencies built in their own separate workspaces are too complicated to link. gtk-rs wants to self-publish their own docs while making all the links to their dependencies point at docs.rs and not have to parse Cargo.lock themselves to do it. Because the feature isn't there, readers get broken links.
• rust-lang/rust#89095: Jump to definition should be seen as a publisher-facing feature, not a reader or author-facing one, because the biggest trade-off related to it (the size of the resulting HTML) is a publisher's concern, and the planned solution with hosting the source viewer as a separate service would also need to be implemented by the publisher (since it involves running a separate database server).

Readers

• rust-lang/rust#93903: There's too much jargon in the UI. People aren't born as experts; it takes time, and Rustdoc is supposed to be their entry point to expertise.
• rust-lang/rust#59829: There's too much UI clutter. We've reduced it since the issue was originally opened, but a way to provide most of the functionality of the disclosure widgets with less visible junk would be appreciated.
• rust-lang/rust#60485: Type based search is an ideal power user feature: it doesn't get in the way of new users very much, and, if it's designed well, it leans on Rust syntax that you already know. Unfortunately, it's not complete.

Footnotes

1. Static Site Generator. Rustdoc, mdBook, Hugo, Jekyll ↩

Leave replies here, or

• https://programming.dev/post/3409605
• https://internals.rust-lang.org/t/rustdoc-html-roles-and-priority-of-constituents/19615