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,
||Raw HTML in doc comments|
||Command line parameters||Patching HTML after running rustdoc|
||Settings popover||Browser extensions, userscripts/userstyles, patching HTML after running rustdoc or downloading a zipball from docs.rs|
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 subling crates'.
- 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.
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.
- 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.
- If I run
- 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 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'.
- 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.
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.
- [rustdoc] Some items don't have documentation rendered · Issue #112379 · rust-lang/rust · GitHub : Authors can't write docs on some items.
- Support for showing explicit enum discriminant values in rustdoc · Issue #101337 · rust-lang/rust · GitHub : Authors can't easily communicate information from code to readers in convenient way.
- Add Mathjax (KaTeX?) Support to Rustdoc · Issue #16300 · rust-lang/rust · GitHub : 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.
- Integrate mdbook into rustdoc · Issue #66249 · rust-lang/rust · GitHub : 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.
- Add search for external crates · Issue #86715 · rust-lang/rust · GitHub : 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 --openlocally.
- Cross-crate links are not always present · Issue #2196 · rust-lang/docs.rs · GitHub : 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.
- Tracking Issue for "jump to definition" · Issue #89095 · rust-lang/rust · GitHub : 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).
- rustdoc: "All items" is misleading due to use of jargon · Issue #93903 · rust-lang/rust · GitHub : 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.
- Rustdoc formatting presents accessibility issues · Issue #59829 · rust-lang/rust · GitHub : 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.
- rustdoc type-based search appears to not support searching by built-in types · Issue #60485 · rust-lang/rust · GitHub : 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.
Static Site Generator. Rustdoc, mdBook, Hugo, Jekyll ↩︎