Rustdoc (HTML) roles and priority of constituents

tools and infrastructure
1

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 subling 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[1] 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

Publishers

Readers

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

3 Likes
2

The GitHub issue links in the post are were broken.

1 Like
3

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.