Add a documentation page. Restructure navigation #241
Conversation
…entation landing page
|
(rust_highfive has picked a reviewer for you, use r? to override) |
The website will [shortly](rust-lang/prev.rust-lang.org#241) provide the main documentation landing page as well as the [FAQ](rust-lang/prev.rust-lang.org#202). All of the content here will be there. This strips out everything and makes the index *just* an index into the in-tree content. My only real qualm with this is that this will become the content on doc.rust-lang.org (a sweet URL), while the main documentation page will be www.rust-lang.org/documentation.html. r? @steveklabnik
|
The docs page looks pretty good to me. I just have a couple of overall worries:
|
|
I've pushed a commit to split out a 'project policies' section. Adding a section on 'policies' generally suggests we need more links there. One possibly is the link explaining Rust governance and processes that I have mentioned to you previously. I've been thinking about adding a footer across the site, particularly to explain how to submit changes to the website itself, possibly to explain the copyright of the website itself. We could add other legal links there, but frankly I think we should not, because they are not so important that that they should be available from every page of the website. I'm going to be doing some work on integrating the FAQ styling with the rest of the site. Part of this may be touching how the header is separated from the content. I'll see if anything there suggests ways to make this header look more balanced. |
|
I've pushed a change to my deployment that adjusts the style of the site to accomodate the styling of the faq. The changes are described here. Part of this adds a border element to most pages near the navbar, and it also reduces the whitespace around the navbar on the index page. |
|
@brson Looking very good! I think the separate policy section works well, and agree that it's a natural place to talk about governance, etc. (Though I don't think we have to do that for this initial round of website updates). My only (very small) nit is that the horizontal rule separating the header from the rest seems thinner than the rule separating the different sections, which felt a bit jarring. But overall the rules and large section headers feel pretty good as a way to present a lot of information in a manageable and simple way. |
|
On reddit @killercup suggested that the syntax index should be advertised more widely. I already added it to rust-learning, and I'm tempted to add it to the references section. |
|
@brson Sounds like a good idea to me. |
This adds a documentation page to the website, to replace the in-tree landing pages, and restructures the top level navigation to have only 'Documentation', 'Community', 'Downloads', and 'Contribute' links.
The security, legal and FAQ pages are all linked from the docs page.
To deal with nightly and beta docs I just included a section called 'nightly and beta documentation' that goes only to the in-tree landing page for those, the thinking being that they are less important, and for more knowledgeable users. So I did not try to duplicate all the relevant information for all three channels ala the downloads page.
For non-english resources I deferred to rust-learning temporarily, though I'd prefer to use the forge for that. I opened a PR against rust-learning to include all the book translations.
For other useful resources I again deferred to rust-learning. To keep things non-overwhelming I like having secondary resources on another page, though perhaps rust-learning will not be that page in the future.
You can see this deployed, along with the contributions page here.
Needs to wait on the contributions page to merge, and if it merges before the FAQ then it needs to be edited to make the FAQ link work.
Fixes #179. cc #175
cc @EFindlay @aturon @steveklabnik