Dungeon.rust-lang.org - Secondary developer docs


#1

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.

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)
  • 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.

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.


Forge.rust-lang.org
Rust Forge - Secondary developer docs
#2

Other naming ideas from IRC: dev, scribble, roughdraft, plumbing, marginalia.


#3

I think this would also be a good place to automatically upload a version of the docs that contain the docs of the rust-internal crates. Currently there’s only an online version by @Manishearth’s at http://manishearth.github.io/rust-internals-docs/rustc/index.html


#4

May I suggest another: arcana.


#5

I suggest any name which is related to rabbits.


#6

I love the idea, I’m just not very happy with any of the names… :slight_smile:


#7

I think this is a great idea, and fwiw I like “dungeon” too


#8

Ooh the rustonomic- fuck.

  • Stiki - static wiki
  • workshop
  • college/university
  • gossip train
  • confessional
  • black market
  • limbo
  • forge
  • asdfhhjkl

#9

Agreed we should host this documentation. Here’s an issue specifically for it.

Nice.

So, so tempting.

I like @Gankro’s ‘forge’ and ‘workshop’ too.


#10

One aspect of this project that I didn’t say anything about in the op is that it can also act as a staging area for content that may belong on the website, but doesn’t possess the quality, or doesn’t yet fit for other reasons.


#11

Another trivial thing to consider: we have a lot of subdomains and it’s fun to abbreviate them: either ‘u.r-l.o’ or even ‘urlo’. To me this says all subdomains ideally start with a unique letter.

‘wrlo’, ‘srlo’, ‘urlo’, ‘irlo’, ‘brlo’, ‘crlo’, ‘drlo’ all taken. Important stuff.


#12

I think there’s a danger of this just being another developer wiki, with all of the disadvantages: the potential to become out of date quickly, poorly maintained, and inconsistent or incomplete. What ideas do you have about mitigating these possibilities? Such as tying documentation to version numbers, page “ownership”, and routine cleanup/triage.


#13

Hmm, “forge.rust-lang.org” -> “frlo” -> “furlough” is kind of punny, but I can’t really make sense of it… :confused:


#14

The main difference I propose to combat quality problems is to limit who can approve changes through the PR process, the main effect of this being to limit which pages are created at all and by whom. The old wiki suffered from many marginal pages that were unmaintained, while also containing several useful pages that were reasonably maintained.


#15

area51.rust-lang.org (abbreviated arlo)?


#16

Just name it developer_docs


#17

grapevine.rust-lang.org


#18

Sorry for the very late reply on this. I feel like this is a pretty plausible way to grow our contributor-oriented content without some of the downsides of wikis (given the review process and clear scope that you outlined).

That said, some of the topics you outlined at the top seem user-focused/like they should go on the main site (or other documentation venues):

  • platform building instructions, musl, android, mipsel, ios, etc, cross compiles
  • tiers and support levels
  • user groups / meetups
  • lists of links to ides, libraries, other tooling etc.
  • collections of videos, talks, blog posts
  • bibliography / references
  • high-profile projects?
  • profiling tips
  • lists of interesting tools to use on/with rust

And a couple were a bit ambiguous (not sure if the “hacks” here are for hacking on rustc itself, or just for using Rust):

  • testing hacks
  • debugging hacks

Can you elaborate on why these topics seemed like a good match for the dungeon, given that they seem of interest to the user community?

Maybe a different way of asking this is: is the split primarily about audience (user vs contrib)? I could imagine that we host some user-oriented content in the dungeon as a kind of pipelining/maturation process (for stuff that’s still changing rapidly, or where we want to iterate for a while before going fully public).


#19

Another thing I would put here is the release process.


#20

I don’t totally see this is being oriented toward devs. It’s an easy way to rationalize its need, but I also see this as being for more dynamic, low-quality, and underbaked documentation.

Not in my view, but others have expressed that desire.