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 contribution 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 name).
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 model.
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.
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)
- relatively static
- 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.
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.