Skip to content
This repository has been archived by the owner on Sep 30, 2020. It is now read-only.

New doc, contribution, and FAQ pages #244

Merged
merged 104 commits into from
Jan 14, 2016
Merged

Conversation

brson
Copy link
Contributor

@brson brson commented Jan 12, 2016

This PR combines the documentation, contribution, and faq PRs along with some extra commits that integrate the FAQ style with the existing website.

It's not perfect, but it's good enough that I'm happy to deploy it as-is and make additional changes as followups.

The only remaining big concerns I have about the FAQ are: HKT section, while better, in the first section makes it sound like Rust has HKT by saying that type constructors that exist are KHTs; there's still no Q&A for 'What does "Rust" mean'.

One last thing I intend to do is make all the FAQs anchors so they can be linked directly, but if necessary that can be a follow up.

Here's what it looks like.

r? @aturon cc @nikomatsakis

@aturon
Copy link
Member

aturon commented Jan 13, 2016

@brson OK, that's fine by me.

@brson
Copy link
Contributor Author

brson commented Jan 13, 2016

Hm, it is possible to set 'with_toc_data' to generate ids on the headers, though that doesn't turn them into links, which is needed to make them discoverable. I also see that my anchor patch is generating incorrect markup. I'll take another pass at it.

@brson
Copy link
Contributor Author

brson commented Jan 14, 2016

I'll resolve the conflicts in @aturon and @nikomatsakis's pulls myself then fix the anchors somehow.

@brson
Copy link
Contributor Author

brson commented Jan 14, 2016

@aturon I did augment your 'fearless refactoring' sentence.

I do want to make the anchors here explicit. Since this page is going to be maintained for a long time, it will give more options when changing header text. I think I'll just replace the markdown headers with h3 tags.

Edit: This markdown is barely markdown now. Lots of html.

@brson
Copy link
Contributor Author

brson commented Jan 14, 2016

Well, I switched all the h3 headers to HTML instead of markdown. This makes the markup super ugly since all the code has to be properly html-escaped but it accomplishes my personal goal of having control of the anchor names.

@brson
Copy link
Contributor Author

brson commented Jan 14, 2016

I've made a few more changes:

I put the project faqs up front since they seem like the logical overview questions. That section had a misplaced 'IDEs' question, so I turned 'Debugging' into 'Debugging and Tooling' and dumped the IDE and rustfmt questions there.

I would have just added a Tooling section, but the 3 column index wants the category count to be a multiple of three.

@aturon
Copy link
Member

aturon commented Jan 14, 2016

@brson

OK, I had time to make it through the Project FAQ: brson#4

I don't think I'll have time to review the "Other Languages" section, but I think @nikomatsakis has gone through that, so at this point I'm happy to 👍

This has been an incredible effort. Thanks especially to @AndrewBrinker for the work on the FAQ!

Changes to Project section of FAQ
brson added a commit that referenced this pull request Jan 14, 2016
New doc, contribution, and FAQ pages
@brson brson merged commit 875f46e into rust-lang:master Jan 14, 2016
@tshepang
Copy link
Member

💃

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants