Add a basic style guide.

Author: ehuss

CONTRIBUTING.md

@@ -14,6 +14,11 @@ for the Reference. As such, we have the warning saying there's work that needs
 to be done. Eventually, we plan to make sure everything is well documented
 enough that we can remove the warning.
 
+It is encouraged for you to read the [introduction] to familiarize yourself
+with the kind of content the reference is expected to contain and the
+conventions it uses. Also, the [style guide] provides more detailed guidelines
+for formatting and content.
+
 ## Critiquing the Reference
 
 This is the easiest way to contribute. Basically, as you read the reference, if
@@ -63,7 +68,9 @@ This should include links to any relevant information, such as the
 stabilization PR, the RFC, the tracking issue, and anything else that would be
 helpful for writing the documentation.
 
+[introduction]: src/introduction.md
 [issue tracker]: https://github.com/rust-lang/reference/issues
 [playpen]: https://play.rust-lang.org/
 [rust-lang/rust]: https://github.com/rust-lang/rust/
+[style guide]: STYLE.md
 [unstable]: https://doc.rust-lang.org/nightly/unstable-book/

STYLE.md

@@ -0,0 +1,80 @@
+# Rust reference style guide
+
+Some conventions and content guidelines are specified in the [introduction].
+This document serves as a guide for editors and reviewers.
+
+## Markdown formatting
+
+* Use ATX-style heading with sentence case.
+* Wrap long lines, preferably at 80-columns.
+* Use reference links, with shortcuts if appropriate. Place the sorted link
+  reference definitions at the bottom of the file, or at the bottom of a
+  section if there is an unusually large number of links that are specific to
+  the section.
+
+    ```
+    Example of shortcut link: [enumerations]
+    Example of reference link with label: [block expression][block]
+
+    [block]: expressions/block-expr.md
+    [enumerations]: types/enum.md
+    ```
+
+* Links should be relative with the `.md` extension. Links to other rust-lang
+  books that are published with the reference or the standard library API
+  should also be relative so that the linkchecker can validate them.
+* See the [Conventions] section for formatting callouts such as notes, edition
+  differences, and warnings.
+* Formatting to avoid:
+    * Avoid trailing spaces.
+    * Avoid double blank lines.
+
+### Code examples
+
+Code examples should use code blocks with triple backticks. The language
+should always be specified (such as `rust`).
+
+```rust
+println!("Hello!");
+```
+
+See https://highlightjs.org/ for a list of supported languages.
+
+Rust examples are tested via rustdoc, and should include the appropriate
+annotations when tests are expected to fail:
+
+* `edition2018` — If it is edition-specific.
+* `no_run` — The example should compile successfully, but should not be
+  executed.
+* `should_panic` — The example should compile and run, but produce a panic.
+* `compile_fail` — The example is expected to fail to compile.
+* `ignore` — The example shouldn't be built or tested. This should be avoided
+  if possible. Usually this is only necessary when the testing framework does
+  not support it (such as external crates or modules, or a proc-macro), or it
+  contains psuedo-code which is not valid Rust. An HTML comment such as
+  `<!-- ignore: requires extern crate -->` should be placed before the example
+  to explain why it is ignored.
+
+See the [rustdoc documentation] for more detail.
+
+## Language and grammar
+
+* Use American English spelling.
+* Use Oxford commas.
+* Idioms and styling to avoid:
+    * Avoid slashes for alternatives ("program/binary"), use conjunctions or
+      rewrite it ("program or binary").
+    * Avoid qualifying something as "in Rust", the entire reference is about
+      Rust.
+
+## Content
+
+* Whenever there is a difference between editions, the differences should be
+  called out with an "Edition Differences" block. The main text should stick
+  to what is common between the editions. However, for large differences (such
+  as "async"), the main text may contain edition-specific content as long as
+  it is made clear which editions it applies to.
+
+[conventions]: src/introduction.md#conventions
+[introduction]: src/introduction.md
+[rustdoc documentation]: https://doc.rust-lang.org/rustdoc/documentation-tests.html