Contributions page

[brson]

Based off of @efindlay's original PR, which was based off ncameron's work.

Rendered.

The idea here is to quickly provide the most important links (e.g. the second paragraph reroutes people to bug reporting), subdivide the deluge of information in a way that is digestible (six sections - issue triage, docs, community building, tooling, libs, compiler), then guide people to other sources of information. I've used prose in an attempt to provide context for newbies to understand the larger picture. Sometimes the same information is provided in different sections, from different perspectives - e.g. fixing easy issues vs. writing easy issues.

Ideally, there is an easy path from here to all relevant information for contributors, but that is not quite true yet, and there are types of information that are just not available. What I want this page to do is to link to other, 'living', landing pages for teams, initiatives, topics, etc., and I've tried to do that as much as possible, but there are some categories of information that are not organized anywhere, so sometimes there is more exposition here than I'd like.

This page occasionally links to, and thus endorses, unofficial projects of interest. I want to be clear though that it is not a free-for-all and we are not open to listing arbitrary projects here.

With the quantity and specificity of info here it'll be prone to bitrot and need periodic attendance.

Problems:

• The prominent link to 'an overview of the organization, processes, and policies' links somewhere uncomprehensive. I'd like to write this, but there's a lot of info to cover and I want a break from writing for a bit.
• Topics of blogging and translation aren't covered.
• #rust-libs may not be the right place to direct people who are interested in out-of-tree libs.

I've run out of steam on this and want to get other eyes on it. The libs and tooling sections were the last I hit and it shows.

Although they are very different, my main influence was Scala's page.

Fixes #177.

cc @aturon @steveklabnik

[rust-highfive]

r? @alexcrichton

(rust_highfive has picked a reviewer for you, use r? to override)

[brson]

This links to the IDEs page, which I have not updated to fit the style of the site. My preference is to move that content to the dungeon/forge.

[badboy]

This sentence needs fixes. I guess at least the solving the issue and submitting the fix GitHub pull request should be changed.

[brson]

Wow, what happened...

[steveklabnik]

I would try to rephrase this to lose the "just", the whole point of these pages is that doing this isn't always as obvious as it may seem. Maybe something like "Found a bug and need to report it?"

[steveklabnik]

"their name in a comment"

[steveklabnik]

I would maybe split that first sentence into two, or use a ; rather than a , after "it"

[brson]

The second clause is self-evident and content free, so I think I'll just remove it.

[brson]

An idea I liked but didn't implement, mainly because it would add even more stuff, is to put an 'active initiatives' section near the front, that would link to things like the forum posts for RWIB, Glacier, IDEs, MIR, etc. Curious what others think.

[steveklabnik]

This post is great, but so old: is it even relevant today?

[brson]

Maybe not. I'll remove it.

[steveklabnik]

👏 👏 👏

[nodakai]

Are we required to read through both of the new contributing.html and the existing CONTRIBUTING.md ? I don't think we need both.

[nodakai]

"Contributing to Rust" carries next to no information. Instead I'd emphasize

There are many ways to contribute to the success of Rust.

because, as I understand it, this document is intended for people who are eager to contribute to Rust but have no idea on where to start.

[brson]

What might be a more descriptive title?

[alexcrichton]

r? @steveklabnik

[englishm]

How might people with UX or visual design backgrounds be able to contribute to Rust?

[iliekturtles]

The &emdash; is not rendering properly: search for "emdash" at http://brson.github.io/rust-www/contribute.html

[brson]

Oops. Should be mdash.

[brson]

Are we required to read through both of the new contributing.html and the existing CONTRIBUTING.md ? I don't think we need both.

CONTRIBUTING.md is displayed on new PRs - it catches people who are familiar with the GitHub ecosystem but not the Rust project. It is also specific to the mechanics of contributing to the rust-lang/rust repository. This page is much broader in scope and links to CONTRIBUTING.md as appropriate for the details.

The content is mostly not duplicated, but I think we can trim down CONTRIBUTING.md.

[brson]

How might people with UX or visual design backgrounds be able to contribute to Rust?

@englishm Unfortunately, we don't have an answer for this right now. We're hoping to put some planning effort into this area soon so we can give better guidance. If somebody is aware of anything we can tell such people or point them toward that would be productive, I'd be interested.

[brson]

I've addressed the current feedback except for @nodakai's concern about the title.

[aturon]

I want to give more in-depth feedback, but for now, my biggest concern is that there's just too much here -- that the page is a bit overwhelming.

Can we think of a way to pull out the most juicy bits into a TL;DR section we can stick at the front? I know triage is acting as part of that, but I'm thinking something even tighter.

Note that the Scala site avoids this problem by having all of the sections actually be independent pages. We could consider that as well.

[brson]

@aturon Yeah, it's a lot. Do you think that the six areas are a reasonable subdivision?

@bstrie has previously expressed an opinion against subpages.

I'll try reorganizing it so this page is less sprawling, with the bulk of the information elsewhere.

[brson]

cc @nrc you may have opinions about this.

[aturon]

@brson Yes, I think the structure and content is great. Just hoping we can get something a bit more inviting a la http://scala-lang.org/contribute/

[nrc]

+1 for subpages - I think it will help make the page feel less overwhelming. Design-wise, I think having more whitespace and a less dense layout will make this feel better, and that is easier with sub-pages, if the landing page has just a few paras of text and some links, it's easier to space it out.

[brson]

OK, I've split each of the 6 subsections into their own pages. See here.

[aturon]

@brson Very nice! I feel like that really makes this whole effort come together.

[aturon]

One further suggestion: make the links to the subsections stand out a bit -- perhaps bold? There are a lot of links here so emphasizing the primary ones is helpful. (See, again, the Scala page for inspiration here.)

[brson]

I've emboldened the subsection links and also removed the prominent governance link temporarily until we have content for it.

[aturon]

@brson: 👍

Btw, are you planning to land these various PRs separately? Or, now that there are cross-cutting style changes, do you want to land them all together?

[brson]

@aturon At this point, with the style changes that affect everything I'm planning on landing them together.

[brson]

Combined PR.