Split up contributing.md

README.md

@@ -81,7 +81,7 @@ The build files are found in the `book/html` directory.
 
 See the guide itself for instructions on [writing new docs].
 
-[writing new docs]: src/contributing.md#contributing-to-rustc-dev-guide
+[writing new docs]: src/contributing-to-guide.md
 
 ## Maintaining the guide
 

src/SUMMARY.md

@@ -51,6 +51,7 @@
 # Contributing to Rust
 
 - [Contribution procedures](./contributing.md)
+- [Writing rustc-dev-guide documentation](./contributing-to-guide.md)
 - [About the compiler team](./compiler-team.md)
 - [Using Git](./git.md)
 - [Mastering @rustbot](./rustbot.md)

src/about-this-guide.md

@@ -35,7 +35,7 @@ There are several parts to this guide:
    There are a few of these with different information, including a glossary.
 
 [p1]: ./building/how-to-build-and-run.md
-[p2]: ./contributing.md
+[p2]: ./getting-started.md
 [p3]: ./building/bootstrapping/intro.md
 [p4]: ./part-2-intro.md
 [p5]: ./part-3-intro.md
@@ -61,7 +61,7 @@ Even better, open a PR with a correction!
 If you do contribute to the guide,
 please see the corresponding [subsection on writing documentation in this guide].
 
-[subsection on writing documentation in this guide]: contributing.md#contributing-to-rustc-dev-guide
+[subsection on writing documentation in this guide]: contributing-to-guide.md
 
 > “‘All conditioned things are impermanent’ —
 > when one sees this with wisdom, one turns away from suffering.”

src/building/compiler-documenting.md

@@ -48,3 +48,36 @@ like the standard library (std) or the compiler (rustc).
   NOTE: The documentation for the compiler is found at [this link].
 
 [this link]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/
+
+## Contributing documentation
+
+Documentation improvements are very welcome.
+The source of `doc.rust-lang.org`
+is located in [`src/doc`] in the tree, and standard API documentation is generated
+from the source code itself (e.g. [`library/std/src/lib.rs`][std-root]). Documentation pull requests
+function in the same way as other pull requests.
+
+[`src/doc`]: https://github.com/rust-lang/rust/tree/HEAD/src/doc
+[std-root]: https://github.com/rust-lang/rust/blob/HEAD/library/std/src/lib.rs#L1
+
+To find documentation-related issues, use the [A-docs label].
+
+You can find documentation style guidelines in [RFC 1574].
+
+To build the standard library documentation, use `x doc --stage 1 library --open`.
+To build the documentation for a book (e.g. the unstable book), use `x doc src/doc/unstable-book`.
+Results should appear in `build/host/doc`, as well as automatically open in your default browser.
+See [Building Documentation](#building-documentation) for more
+information.
+
+You can also use `rustdoc` directly to check small fixes.
+For example, `rustdoc src/doc/reference.md` will render reference to `doc/reference.html`.
+The CSS might be messed up, but you can verify that the HTML is right.
+
+Please notice that we don't accept typography/spellcheck fixes to **internal documentation**
+as it's usually not worth the churn or the review time.
+Examples of internal documentation are code comments and rustc API docs.
+However, feel free to fix those if accompanied by other improvements in the same PR.
+
+[A-docs label]: https://github.com/rust-lang/rust/issues?q=is%3Aopen%20is%3Aissue%20label%3AA-docs
+[RFC 1574]: https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text

src/contributing-to-guide.md

@@ -0,0 +1,82 @@
+# Writing rustc-dev-guide documentation
+
+Contributions to the [rustc-dev-guide] are always welcome, and can be made directly at
+[the rust-lang/rustc-dev-guide repo][rdgrepo].
+The issue tracker in that repo is also a great way to find things that need doing.
+There are issues for beginners and advanced compiler devs alike!
+
+Just a few things to keep in mind:
+
+[rustc API docs]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle
+
+- When writing about a particular part of the compiler's code, we
+  recommend that you link to the relevant parts of the [rustc API docs].
+
+- Use sentence case for chapter and section titles.
+
+- Use dashes (`-`) to separate words in file names.
+
+- Links within the guide should use `.md` relative links, not `.html` links.
+  CI will enforce this.
+
+- Please try to avoid overly long lines and use semantic line breaks (where you break the line after each sentence).
+  This makes it easier to review diffs, since they avoid reflowing other unrelated prose.
+  There is no strict limit on line lengths;
+  let the sentence or part of the sentence flow to its proper end on the same line.
+
+  You can use a tool in ci/sembr to help with this.
+  Its help output can be seen with this command:
+
+  ```console
+  cargo run --manifest-path ci/sembr/Cargo.toml -- --help
+  ```
+
+- When contributing text to the guide, please contextualize the information with some time period
+  and/or a reason so that the reader knows how much to trust the information.
+  Aim to provide a reasonable amount of context, and consider including:
+
+  - A reason for why the text may be out of date other than "change",
+    as change is a constant across the project.
+
+  - The date the comment was added, e.g. instead of writing _"Currently, ..."_
+    or _"As of now, ..."_, consider adding the date, in one of the following formats:
+    - Jan 2021
+    - January 2021
+    - jan 2021
+    - january 2021
+
+    There is a CI action (in `.github/workflows/date-check.yml`)
+    that generates a monthly report showing those that are over 6 months old
+    ([example](https://github.com/rust-lang/rustc-dev-guide/issues/2052)).
+
+    For the action to pick the date, add a special annotation before specifying the date:
+
+    ```md
+    <!-- date-check --> Jul 2026
+    ```
+
+    Example:
+
+    ```md
+    As of <!-- date-check --> Jul 2026, the foo did the bar.
+    ```
+
+    For cases where the date should not be part of the visible rendered output,
+    use the following instead:
+
+    ```md
+    <!-- date-check: Jul 2026 -->
+    ```
+
+  - A link to a relevant WG, tracking issue, `rustc` rustdoc page, or similar, that may provide
+    further explanation for the change process or a way to verify that the information is not
+    outdated.
+
+## ⚠️ Note: Where to contribute `rustc-dev-guide` changes
+
+For detailed information about where to contribute rustc-dev-guide changes and the benefits of doing so,
+see [the rustc-dev-guide team documentation].
+
+[rustc-dev-guide]: https://rustc-dev-guide.rust-lang.org/
+[rdgrepo]: https://github.com/rust-lang/rustc-dev-guide
+[the rustc-dev-guide team documentation]: https://forge.rust-lang.org/rustc-dev-guide/index.html#where-to-contribute-rustc-dev-guide-changes