It comes up frequently that I or another team member needs to document
some aspect of Rust or its development process. Because there is a
very high bar for getting content on the website proper, at the moment
these sorts of docs end up in private repos or on the forums. I've
felt this again recently as I've been compiling a comprehensive
page for the website, as contributor-oriented content I'd like to link
to doesn't always live anywhere great (it contains for example some
links to the old wiki).
I want to rectify that and create a section of the website that is
suitable for important documentation that is either: changing rapidly,
lower quality, unsuitable for the main website or in-tree docs. These
docs tend to be oriented toward developers of the Rust project itself,
recording common wisdom about how the project works in practice, about
active and upcoming initiatives.
So introducing The Rust Dungeon (don't worry; we can bikeshed the
Also, sorry this proposal is really rough. I threw it together
quickly. Scroll to the end for the actual proposal.
Examples of types of documents that may belong in such a place:
- platform building instructions, musl, android, mipsel, ios, etc, cross compiles
- packaging guidelines
- tiers and support levels
- infrastructure documentation
- communmity buildslave contacts
- #rust-bots owners
- fott archives
- release history and artifacts
- build system tricks
- project initiatives
- user groups / meetups
- lists of links to ides, libraries, other tooling etc.
- collections of videos, talks, blog posts
- bibliography / references
- high-profile projects?
- testing hacks
- debugging hacks
- profiling tips
- lists of interesting tools to use on/with rust
- roadmap / planning
- list of infrastructure tools (homu, highfive, etc.)
I'm curious to hear specific examples of existing or non-existing dev
docs that others expect to have access to, that might fit into this
If we had this I would immediately move the fott list, the test suite
description, the bibliography, the infrastructure docs, and probably
the ide's page over to it.
Criteria for different documentation venues
It's not clear to me exactly what the criteria is for website content
vs. dungeon conten. To a quick approximation I'd say the content of
the website is:
- user-oriented (though the contributing page is a jumping off point for lots of dev-oriented content)
- precisely worded
- carefully reviewed
The dungeon is:
- contributor oriented
- dynamically changing content
- lower quality standards
- loosely reviewed
For example I'd prefer the existing ides
page live in this section of the
web site. Not because the content isn't up to website standards (it
isn't quite - but that's easy to rectify), but because it describes an
active initiative. It's not a page about IDEs for Rust generally, it's
about a project to improve IDEs, the state of which will presumably
change over the months of the project. If we had a page about Rust
tooling that was oriented not toward contributors, but users, that
would feel more like website content to me.
Finally, there's also a role for the forums in contrtibutor-oriented
documentation. I've been pretty satisfied with using long-lived
threads for organizing ongoing project initiatives, like TWiR,
Glacier, PRP, RWIB. These threads can be updated as needed,
support markdown, and stay visible as long as they are active, to fade
away gracefully when nobody is paying attention to them any longer.
The actual proposal
Create a new repo, rust-lang/dungeon (we can bikeshed), that is
a static Jekyll site. In most respects it is set up like rust-lang/rust-www,
but it is published to dungeon.rust-lang.org. It is styled similar to the
website but different, to make it clear that the content is categorically
different from the main website (like urlo and irlo are styled differently,
though this will probably be more dramatic).
It's modified through the PR process. Adding pages takes close
consideration from the team, to keep a lid on wiki-like sprawl,
but modifying existing pages does not require the careful review that
the main website does. I expect that every page will end up having
essentially one owner who cares for it.
Each page might also contain a link explaining how to modify the page
and open a PR against it.