Rusty Web Improvement Bureau

[brson]

Rusty Web Improvement Bureau

8 simple missions to improve the Rust web presence. Should you choose to accept them.

The Rust Project is assembling an elite team of hackers to execute a number of vital missions for the betterment of The Rust Website. It will be dangerous. You’ll be deep in enemy territory. But if you return alive you will be a hero, your name praised and your tales recounted from Rustonia to the Galvanic Sea!

Sign up below for daring and adventure.

Wut?

This is a project to better surface some crucial information through the Rust website.

A major theme of this work is organizing and increasing the sub-pages on the main website so there is more room for expansion. The website started as just a home page, then added an install page. Now we’ve also got the team page, the code of conduct, and also the security policy (which is not linked from anywhere on the website).

After this overhaul we will have the following pages:

• Home Page
• Documentation
• Downloads
• Community
• Contributing
• Teams
• Security Policy
• Code of Conduct
• Stability Guarantee
• FAQ

Each will be a work of stunning beauty.

Below are descriptions of, and links to, 8 issues describing limited improvements that I, @aturon, @steveklabnik, and others would like to make to Rust’s websites. We need help though. If you can help, say in this thread what assignments interest you and we’ll divide them up. Feel free to leave suggestions too, though please make them specific and constrained more-or-less to the scope established below. This is not the thread to talk about major redesigns.

Please give this a look and see what you think. In general, I’ve described how I think they should be implemented, some in more detail than others. I’m open to limited debate about the specifics but also want to get this moving fast to make the information available.

• Mission 1: Front page overhaul and nav restructure
• Mission 2: Community page
• Mission 3: Contributing page
• Mission 4: Stability guarantee
• Mission 5: Documentation page
• Mission 6: A better example
• Mission 7: FAQ fixes
• Mission 8: Download page tweaks
• References and Resources

Mission 1: Front page overhaul and nav restructure

Special agent on assignment: TBD

Issue link: https://github.com/rust-lang/rust-www/issues/175

The amount of content we need to present is outgrowing our nav bar. Community links are growing and there are lots more links we need to expose but no room.

Completely restructure the nav bar as a few ‘category’ links that lead to their own pages:

• Documentation
• Community
• Downloads
• Contributing

The content of these pages is discussed in further missions below. Because this adds ‘downloads’ to the navbar, we also need to remove the redundant ‘Other Downloads’ button.

There are some other important links that need to be integrated into the front page:

• crates.io - It takes a lot of clicks to discover that crates.io exists today! I don’t know the best way to integrate this, but one possibility is to call the crate ecosystem out in the feature list and hyperlink there.
• play.rust-lang.org - To discover play.rlo you have to click ‘Run’, then the ‘fold-out’ icon. This is a useful enough newbie tool that it ought be completely obvious how to find it. Again, no great ideas about where this link lives in the current design.
• stability guarantee - I like the idea of adjusting the sales pitch / feature list to tout stability and making this an inline link there. This isn’t written yet, discussed below in another missions.
• security policy - The page exists but isn’t linked.
• GitHub - via banner is fine.

If these can’t all be integrated organically into the flow of the page then you might consider adding them to a new footer.

Consider making the feature list link to various blog posts. Make sure the page style continues to attract attention to the more crucial links we already have.

Propose tweaks to the design to accomplish all these goals.

Mission 2: Community page

Special agent on assignment: @efindlay

Issue link: https://github.com/rust-lang/rust-www/issues/176

Today the navbar is overrun by ‘community’ links, but still there is more info to disseminate. Create a new page, to be linked from a single new ’Community’ navbar link. This page needs to be a friendly and accessible intro to the world of Rust.

Subjects covered should include:

• The importance of the COC (with link) and diversity
• Team structure (with link)
• The community and moderation teams in particular
• The RFC process, with link to RFC readme
• Subteam reports and TWiR
• Forums, IRC and other communication venues
• It should explicitly explain how to get help
• Calendar. Try to embed a combination of the event calendar and the release calendar.
• List of meetup groups
• blog
• twitter

Think about how to organize this by audience. Some community members are devs and some are users. Consider that the primary audience for this page is mostly users, for the contributing page is mostly devs.

Come up with a design that conveys all of this information, either directly or through additional links, without being overwhelming. This will be one of the most important newbie resources.

I’m most worried here about conveying a dedication to diversity, as we don’t have a lot of existing material to crib off of, there’s overlap with the CoC, and anything we say needs to be worded artfully.

Adapt material from the current docs.

Mission 3: Contributing page

*Special agent on assignment: @sirDonQui *

Issue link: https://github.com/rust-lang/rust-www/issues/177

Create a contributing page that adapts nrc’s stuff and CONTRIBUTING.md.

It should be simple and accessible, with consideration for non-coding contributions.

• It should have a link to instructions on submitting bug reports.
• It should lead people to instructions for getting involved in RFC process.
• It should provide leads for getting involved in evangelism.

It might highlight major initiatives, like IDE’s. Such initiatives would need stable landing pages to link to, like internals threads or GitHub issues.

Cross-link with CONTRIBUTING.md.

Scala’s page is good to crib off of.

Mission 4: Stability guarantee

Special agent on assignment: @geofft

Issue link: https://github.com/rust-lang/rust-www/issues/178

Write a simple, user-oriented ‘stability guarantee’, based off of the API evolution RFC, Language versioning RFC, and Stability as a Deliverable.

This should be a few paragraphs designed to make newcomers feel good about trusting Rust. This will be linked prominently from the front page and will be an important part of the Rust sales pitch. Use your creativity.

Mission 5: Documentation page

Special agent on assignment: TBD

Issue link: https://github.com/rust-lang/rust-www/issues/179

Today, the documentation landing page lives in the Rust tree, and is generated for each release channel. As Rust grows though, more documentation lives out of tree and needs to be discoverable.

Let’s reorganize this so that the website itself is the main landing page for finding docs.

Start by moving the contents of the existing documentation index into rust-www, reducing the existing doc index to links to the in-tree docs, as well as a link to the website for more information.

Add a link to the new website-based FAQ.

Brainstorm about other documentation we might want to link to and what standards of quality and stability we might require before officially endorsing them.

Mission 6: A better example

Special agent on assignment: TBD

Issue link: https://github.com/rust-lang/rust-www/issues/180

Come up with a new example that fits in the same space and exemplifies the Zen of Rust. This is a newb’s first impression of Rust and it needs to be breathtaking.

Consider that we might have multiple examples serving different purposes and put them on a carousel, only if it’s not possible to create a single succinct example.

Mission 7: FAQ fixes

Special agent on assignment: @AndrewBrinker

Issue link: https://github.com/rust-lang/rust-www/issues/181

The FAQs have more-or-less been bitrotting since the inception of the project. They are only slightly better than useless.

Start a thread on users.rlo asking for people to write boths Q’s and A’s. Throw away the 3 existing FAQs and write a single new one. Put this one on the website, linked from the doc page.

Q’s

Why is the Rust [HashMap] so slow?

• http://cglab.ca/~abeinges/blah/hash-rs/
• https://www.reddit.com/r/rust/comments/3hw9zf/rust_hasher_comparisons/

Mission 8: Download page tweaks

Special agent on assignment: @brson

Issue link: https://github.com/rust-lang/rust-www/issues/182

Rename from install.html to downloads.html, to match the 'Downloads’ link. The name ‘Downloads’ gives us room to expand to offer things that are not installers. Leave a redirect.

To the beta channel, add an indication of which date it will become stable.

Add links to changelogs and/or release announcements, as well as the docs for each channel.

Simplify labels by removing the words ‘binaries’ and ‘installer’. This is a meaningless distinction these days and just adds noise.

Two options for mac is too much choice w/o no obvious way to know which one to pick. Remove one of them. I’ve started a poll to decide which:

Which Rust installer for Mac do you use (poll)? • r/rust

Consider whether we need a better-organized archive to give access bonus artifacts like the extra mac installer.

References and Resources

• https://www.haskell.org/documentation
• http://scala-lang.org/documentation/
• http://golang.org/doc/
• https://docs.python.org/3/
• https://rust.zeef.com/harris.brakmic
• https://github.com/ctjhoa/rust-learning

[sinistersnare]

Would love to help with 6 and 7, but as the semester starts Monday, I probably don’t want to commit to anything. I would be happy to work with whoever does take those mantles, however!

[aturon]

I’m interested in taking a couple of these on – I’m glad to help where it’s most needed, but would particularly like to work on #1 and #7!

[tikue]

This is awesome. #6 is so hard. I think it definitely needs to involve borrows off the main thread.

[td_]

The FAQs have more-or-less been bitrotting since the inception of the project. They are only slightly better than useless.

Start a thread on users.rlo asking for people to write boths Q’s and A’s. Throw away the 3 existing FAQs and write a single new one. Put this one on the website, linked from the doc page

The current FAQs are decidedly not great as FAQs (the language design “FAQ” is mostly not even structured as questions & answers!), but they are a really fun insight into some historical thoughts that shaped the Rust project. Without strong controls, FAQs become the util directory of documentation: junk drawers for the random assortment of facts project members wanted to write up.

Not really sure what an FAQ for a programming language is supposed to be though. FAQs can be a good, focused alternative to a manual for simple tools if they’re written well, but a language is not a simple tool. Here are the FAQs for various other languages, for reference:

• Clojure
• D
• Go
• Haskell
• Nim
• Perl
• Python
• Ruby (Not hosted with the official documentation.)

Maybe I’m unusual, but my experience with FAQs has never been that I looked up the FAQ before asking a question; I’ll use a search engine to try to find the answer, but I won’t specifically check the FAQ table of contents. I think where FAQs can really shine is as as a high-level overview of the language and project, which can be reasonably read in one sitting, written in an informal and catechistic manner while still being detached and subdued. I read FAQs to find out if their subject is something I’m interested in.

[SimonSapin]

also the security policy (which is not linked from anywhere on the website).

Is this a bug or deliberate?

[steveklabnik]

s this a bug or deliberate

It’s a bug. We don’t actually have a security announcement email list, which is an important part of the policy. It’s been brought up a few times but the discussion gets stuck in “should we host our own” vs “just make a Google Group and be done with it”

[geofft]

I’d be interested in helping with 6 and perhaps 4.

Regarding a security mailing list, would using some service like TinyLetter resolve the concerns (I assume they’re approximately “self-hosting sucks” and “people have feelings about Google”)? I’m a fan of self-hosting, but email deliverability is challenging without a third-party service.

[lambda]

I’ve elaborated on my thoughts on the front page example in the linked ticket. I think that it would be better to do a few different examples targeted towards particular features, rather than trying to cram everything into a single example. I will be proposing a few examples for a few different features over the next few days, but I’d also love to see other people propose some good, short, self-contained examples of some of the other major selling points of Rust.

I also have a few global questions about this initiative.

Is there anyone working on an overall design theme for the site? Is it intended that people taking over each of these tasks will be doing the full design of each page, or perhaps producing some content and basic structure and then letting somone with better design experience come up with a coherent design? I notice that lots of languages have recently had overhauls of their website with a focus on design, like Haskell and Python, and I think it would be good to have a more coherent design than just “basic Bootstrap plus a logo”. Does this fall under “Mission 1”, or is it distinct?

Has there been any thought about internationalization of the site? Would that be done on a global basis, or should that be done per-area? I know that for some of these areas, there have been some third-party efforts for translation or language-specific resources, such as the German forum, translation of some of the docs, etc. As part of the global navigation design, it would be good to decide how internationalization plays in with that; should there just be one site in English with the various international resources linked from the appropriate places, or a site-wide internationalization effort where the docs and community pages would point towards the appropriate localized resources (as well as the English language resources, since that is where the bulk of the community is at the moment).

[lambda]

I should probably also say here; I am interested in working on the front page example (mission #6). As I’ve pointed out, I think the best way to do it is a few small examples highlighting different features, rather than one be-all, end-all example of the language. I can start writing up a few examples that I think of, but I would also welcome contributions of what features people think should be highlighted by examples, as well as interesting examples people have of the features I’ve already discussed (in the linked ticket).

I am also interested in working on mission #2, the community page. There’s a lot of content to try to write and organize there. My “global questions” from my last comment were mostly written with that mission in mind; is the person taking one of the missions taking full responsibility for design and implementation of the page, or will there be anyone taking on design responsibilities, and so the mission be more for basic organization and content? And also, how does internationalization play into this; is there going to be any global level internationalization effort, or should it all be English for now, with the appropriate localized resource mentioned in the appropriate places?

[steveklabnik]

Is there anyone working on an overall design theme for the site?

We do want to do some visual refresh work, but content comes first.

[lambda]

We do want to do some visual refresh work, but content comes first.

Yeah, I understand that. However, in some cases the design can influence the organization of the contents. For example, see the Python Community page, which has a large heading introducing the page, plus four columns of information, which is based on the overall site design.

So, if there were going to be any overall visual refresh as well, that might influence the design of the subpages. However, if that’s not on the table for this project, that’s good to know too, as it means just sticking to a fairly basic organizational structure that can be done well within the existing basic Boostrap theme, which is fine.

I guess the one major question that still needs to be answered by mission #1 is the overall nav structure of the site. The current header has gotten a little bit cumbersome, and given that this project will introduce more pages, it’s likely that we’ll want a top level header with the top level sections, and then some way to navigate within each. Is that going to be a second level header? A nav bar to the side? Rollover menus? The different choices influence the branching factor that you can do, and the space you have to work with in the content area, which can influence how you break things down into different topics.

[petrochenkov]

I notice that lots of languages have recently had overhauls of their website with a focus on design, like Haskell and Python, and I think it would be good to have a more coherent design than just “basic Bootstrap plus a logo”.

Can I register my vote against anything reminding the new https://www.haskell.org or pages from random startup generator. The current minimalistic design seems near perfect.

[lambda]

I am a fan of fairly minimalist and simple. On the other hand, whenever I see something using a stock Wordpress theme or just plain Bootstrap, it comes off as cheap and without a lot of effort. I would prefer something with just a little bit more customization and personality, not a “white Helvetica over blurry full screen pictures with scrolling effects” kind of thing like a lot of modern design tends towards.

I feel like something like the Playpen has a little more of a “Rust” feeling, as well as the feeling that someone has spent a little bit of effort on it, than the homepage does, so it would be nice to have a consistent style across the sites that felt like there were a consistent branding, rather than just plain old Bootstrap blue buttons.

Anyhow, as Steve has said that this initiative is more about getting the content right first, and a visual overhaul would come later, I don’t think we need to discuss preferred visual designs here. I had been asking if a visual redesign would be part of the project, as it can sometimes inform the organization of content, but if there is no visual refresh then that’s good to know too.

[brson]

Thanks for linking to those other FAQs @td_. C++ also has a legendary FAQ.

Is there anyone working on an overall design theme for the site? Is it intended that people taking over each of these tasks will be doing the full design of each page, or perhaps producing some content and basic structure and then letting somone with better design experience come up with a coherent design? I notice that lots of languages have recently had overhauls of their website with a focus on design, like Haskell and Python, and I think it would be good to have a more coherent design than just “basic Bootstrap plus a logo”. Does this fall under “Mission 1”, or is it distinct?

Nobody is working on a new design. That is a considerably larger effort than we’re ready to undertake. For this effort, I expect people to use basic layout that fits with the existing theme.

Has there been any thought about internationalization of the site? Would that be done on a global basis, or should that be done per-area?

Interesting question. I have not put any thought into it. For now I think our bet bet is to link to unofficial non-English resources where appropriate.

[brson]

is the person taking one of the missions taking full responsibility for design and implementation of the page, or will there be anyone taking on design responsibilities, and so the mission be more for basic organization and content?

The agent on assignment will be basically responsible, but I (and presumably @steveklabnik) will be happy to offer feedback.

All english for now.

I guess the one major question that still needs to be answered by mission #1 is the overall nav structure of the site. The current header has gotten a little bit cumbersome, and given that this project will introduce more pages, it’s likely that we’ll want a top level header with the top level sections, and then some way to navigate within each. Is that going to be a second level header? A nav bar to the side? Rollover menus? The different choices influence the branching factor that you can do, and the space you have to work with in the content area, which can influence how you break things down into different topics.

If I understand your question, my preference is to not add a second level nav structure to the menu. Just a few links that lead to other pages.

[brson]

OK, thanks to everybody who spoke up! Let’s empower people to make these changes. We’ll start with the easy ones first.

@td_ and @AndrewBrinker you both have opinions about the FAQ (mission 7). @AndrewBrinker you suggested in the FAQ issue you would be interested in cleaning up the existing questions. Will you get started on that now, maybe also consolidating them into one document? @td_ perhaps you could put together an outline based off your research of what would make a good Rust FAQ.

@geofft You are the only person who spoke to the stability guarantee (mission 4). This is a great self-contained task that mostly just requires writing something pursuasive. Will you tackle this?

@lambda You have a lot of well-considered ideas about how to present examples (mission 6). It seems like the consensus is for multiple examples. Can you start pulling together a few key examples based on you and @AndrewBrinker’s ideas in the corresponding issue, and thinking about how to integrate that into the front page? Perhaps @AndrewBrinker will help with examples, and this is an easy thing to solicit opinions on via the forums.

With the variety of opinions about the front page, ISTM that working on just integrating a better example is a good starting point while we hash out other details.

Since there are many opinions about the critical front page, and several good suggestions have been made, I want to mull it over for another day before suggesting somebody start hacking.

OK, at this point missions 1 (front page), 4 (stability guarantee), 6 (examples), and 7 (faq) have stirred up some interest.

That means that mission 2 (community), mission 3 (contributing), mission 5 (docs), and 8 (downloads) all need passionate champions. The hour is nigh, Rustaceans. Come forth and claim your glory.

[AndrewBrinker]

@AndrewBrinker you suggested in the FAQ issue you would be interested in cleaning up the existing questions. Will you get started on that now, maybe also consolidating them into one document?

Yup, no problem. I’ll make a pull request once I’ve got something usable.

Edit: For anyone who wants to see what I’m doing, you can find it here: https://github.com/andrewbrinker/rust-www/tree/faq

[brson]

OK, I’ve assigned #7 to @AndrewBrinker. I’ve also assigned #8 to myself. I’ll aim to get it done next week.

[geofft]

@geofft You are the only person who spoke to the stability guarantee (mission 4). This is a great self-contained task that mostly just requires writing something pursuasive. Will you tackle this?

On it; you can assign the GH issue to me. I’m assuming that it’s in-scope to talk at a high level about how to write forward-compatible code (e.g. “don’t poke at struct layout”, “don’t use glob imports”, plus a link to more details), but out-of-scope to talk about specific [breaking-change]s since 1.0. Let me know if I should be adjusting the focus.

As a thing to link to, it might be worth having a book chapter with more in-depth coverage in the future, but for now I’ll link to the RFCs.