rust-lang · nikomatsakis · Jan 17, 2018 · Jan 17, 2018 · Jan 17, 2018
diff --git a/README.md b/README.md
@@ -1,3 +1,25 @@
-An attempt to document how the compiler works. The intention is to
-bootstrap this "in repo" and eventually move the text over into the
-main rustc repo.
+This is a collaborate effort to build a guide that explains how rustc
+works. The aim of the guide is to help new contributors get oriented
+to rustc, as well as to help more experienced folks in figuring out
+some new part of the compiler that they haven't worked on before.
+
+The guide can be useful today, but it has a lot of work still go.
+Once it gets more complete, the plan is probably to move it into the
+[main Rust repository](https://github.com/rust-lang/rust/).
+
+### Contributing to the guide
+
+If you'd like to help finish the guide, we'd love to have you! The
+main tracking issue for the guide
+[can be found here](https://github.com/rust-lang-nursery/rustc-guide/issues/6). From
+there, you can find a list of all the planned chapters and subsections
+-- if you think something is missing, please open an issue about it!
+Otherwise, find a chapter that sounds interesting to you and then go
+to its associated issue. There should be a list of things to do.
+
+**In general, if you don't know how the compiler works, that is not a
+problem!** In that case, what we will do is to schedule a bit of time
+for you to talk with someone who **does** know the code, or who wants
+to pair with you and figure it out.  Then you can work on writing up
+what you learned.
+
diff --git a/src/src/SUMMARY.md → src/SUMMARY.md b/src/src/SUMMARY.md → src/SUMMARY.md
diff --git a/src/src/chap-010-how-to-build-and-run.md → src/chap-010-how-to-build-and-run.md b/src/src/chap-010-how-to-build-and-run.md → src/chap-010-how-to-build-and-run.md
diff --git a/src/src/chap-020-running-tests.md → src/chap-020-running-tests.md b/src/src/chap-020-running-tests.md → src/chap-020-running-tests.md
diff --git a/src/src/chap-030-walkthrough.md → src/chap-030-walkthrough.md b/src/src/chap-030-walkthrough.md → src/chap-030-walkthrough.md
diff --git a/src/src/chap-040-compiler-conventions.md → src/chap-040-compiler-conventions.md b/src/src/chap-040-compiler-conventions.md → src/chap-040-compiler-conventions.md
diff --git a/src/src/chap-050-the-parser.md → src/chap-050-the-parser.md b/src/src/chap-050-the-parser.md → src/chap-050-the-parser.md
diff --git a/src/src/chap-060-macro-expansion.md → src/chap-060-macro-expansion.md b/src/src/chap-060-macro-expansion.md → src/chap-060-macro-expansion.md
diff --git a/src/src/chap-070-name-resolution.md → src/chap-070-name-resolution.md b/src/src/chap-070-name-resolution.md → src/chap-070-name-resolution.md
diff --git a/src/src/chap-080-hir-lowering.md → src/chap-080-hir-lowering.md b/src/src/chap-080-hir-lowering.md → src/chap-080-hir-lowering.md
diff --git a/src/src/chap-090-ty.md → src/chap-090-ty.md b/src/src/chap-090-ty.md → src/chap-090-ty.md
diff --git a/src/src/chap-100-type-inference.md → src/chap-100-type-inference.md b/src/src/chap-100-type-inference.md → src/chap-100-type-inference.md
diff --git a/src/src/chap-110-trait-resolution.md → src/chap-110-trait-resolution.md b/src/src/chap-110-trait-resolution.md → src/chap-110-trait-resolution.md
diff --git a/src/src/chap-120-type-checking.md → src/chap-120-type-checking.md b/src/src/chap-120-type-checking.md → src/chap-120-type-checking.md
diff --git a/src/src/chap-130-mir-construction.md → src/chap-130-mir-construction.md b/src/src/chap-130-mir-construction.md → src/chap-130-mir-construction.md
diff --git a/src/src/chap-140-mir-borrowck.md → src/chap-140-mir-borrowck.md b/src/src/chap-140-mir-borrowck.md → src/chap-140-mir-borrowck.md
diff --git a/src/src/chap-150-mir-optimizations.md → src/chap-150-mir-optimizations.md b/src/src/chap-150-mir-optimizations.md → src/chap-150-mir-optimizations.md
diff --git a/src/src/chap-160-trans.md → src/chap-160-trans.md b/src/src/chap-160-trans.md → src/chap-160-trans.md
diff --git a/src/src/glossary.md → src/glossary.md b/src/src/glossary.md → src/glossary.md