docs(contrib): polish documentation guide and make it a chapter

src/doc/contrib/src/SUMMARY.md

@@ -24,3 +24,4 @@
     - [Writing Tests](./tests/writing.md)
     - [Benchmarking and Profiling](./tests/profiling.md)
     - [Crater](./tests/crater.md)
+- [Documentation](./documentation/index.md)

src/doc/contrib/src/documentation/index.md

@@ -1,14 +1,31 @@
-# Cargo documentation
+# Documentation
 
-This directory contains Cargo's documentation. There are two parts, [The Cargo
-Book] which is built with [mdbook] and the man pages, which are built with
-[mdman].
+Cargo has several types of documentation that contributors work with:
+
+* [The Cargo Book]
+  * The primary user-facing Cargo documentation
+  * Source at <https://github.com/rust-lang/cargo/tree/master/src/doc>
+  * Built with [mdbook]
+  * Published through ["the doc publishing process"]
+* Man pages
+  * Man pages of the `cargo` command
+  * Built with [mdman]
+  * Published through ["the doc publishing process"]
+* [Contributor guide]
+  * This guide itself
+  * Source at <https://github.com/rust-lang/cargo/tree/master/src/doc/contrib>
+  * Published independently on GitHub Pages at
+    <https://rust-lang.github.io/cargo/contrib>
+    when committing to the master branch.
 
 [The Cargo Book]: https://doc.rust-lang.org/cargo/
+[Crate API docs]: https://docs.rs/cargo
+[Contributor guide]: https://rust-lang.github.io/cargo/contrib
 [mdBook]: https://github.com/rust-lang/mdBook
 [mdman]: https://github.com/rust-lang/cargo/tree/master/crates/mdman/
+["the doc publishing process"]: ../process/release.md#docs-publishing
 
-### Building the book
+## Building the book
 
 Building the book requires [mdBook]. To get it:
 
@@ -30,31 +47,59 @@ on the book:
   rebuilds the book whenever any file changes and automatically reloads your
   web browser.
 
-The book contents are driven by the [`SUMMARY.md`](src/SUMMARY.md) file, and
-every file must be linked there.
+The book contents are driven by a `SUMMARY.md` file,
+and every file must be linked there.
+See <https://rust-lang.github.io/mdBook/> for its usage.
 
-### Building the man pages
+## Building the man pages
 
-The man pages use a tool called [mdman] to convert markdown to a man page
-format. Check out the documentation at
-[`mdman/doc/`](../../crates/mdman/doc/)
-for more details.
+The man pages use a tool called [mdman] to convert Markdown templates into several output formats.
+See <https://github.com/rust-lang/cargo/tree/master/crates/mdman/doc>
+for usage details and template syntax.
 
-The man pages are converted from a templated markdown (located in the
-[`src/doc/man/`](man)
-directory) to three different formats:
+The templates are located in
+<https://github.com/rust-lang/cargo/tree/master/src/doc/man>
+and are converted into three formats:
 
-1. Troff-style man pages, saved in [`src/etc/man/`](../etc/man).
-2. Markdown (with some HTML) for the Cargo Book, saved in
-   [`src/doc/src/commands/`](src/commands).
-3. Plain text (needed for embedded man pages on platforms without man such as
-   Windows), saved in [`src/doc/man/generated_txt/`](man/generated_txt).
+1. Troff man pages --- used by the `cargo help` command,
+   and by distributions to provide man pages which people can install,
+   saved in <https://github.com/rust-lang/cargo/tree/master/src/etc/man>.
+2. Plain text --- used for embedded help on platforms without `man` (such as Windows),
+   saved in <https://github.com/rust-lang/cargo/tree/master/src/doc/man/generated_txt>.
+3. Markdown (with some HTML) --- used for the Cargo Book,
+   saved in <https://github.com/rust-lang/cargo/tree/master/src/doc/src/commands>.
 
 To rebuild the man pages, run `cargo build-man` inside the workspace.
 
-### SemVer chapter tests
+## Writing guidelines
 
-There is a script to verify that the examples in the SemVer chapter work as
+Cargo's documentation is a collective effort,
+so there isn't a single fixed writing style.
+We recommend following the style of the surrounding text to keep things consistent.
+
+A few important guidelines:
+
+* The [Cargo Commands](https://doc.rust-lang.org/nightly/cargo/commands/index.html)
+  chapters in the book are generated from man page templates.
+  To update them, see the [Building the man pages](#building-the-man-pages) section.
+  Do not edit the generated Markdown files directly.
+* Links to pages under <https://doc.rust-lang.org/> should use relative paths.
+  This ensures versioned docs are redirected correctly.
+  For example, if you are at <https://doc.rust-lang.org/cargo/reference/config.html>
+  and want to link to <https://doc.rust-lang.org/rustc/codegen-options/index.html>,
+  you should write the link as `../../rustc/codegen-options/index.html`.
+  This rule doesn't apply if you specifically want to link to docs of a fixed version or channel.
+* When renaming or removing any headings or pages,
+  make sure to set up proper redirects via the [`output.html.redirect`] mdbook option.
+* If a section refers to a concept explained elsewhere
+  (like profiles, features, or workspaces), link to it.
+  That keeps the book navigable without duplicating content.
+
+[[`output.html.redirect`]]: https://rust-lang.github.io/mdBook/format/configuration/renderers.html#outputhtmlredirect
+
+## SemVer chapter tests
+
+There is a script to verify that the examples in [the SemVer chapter] work as
 intended. To run the tests, run `cargo +stable run -p semver-check`.
 
 Note that these tests run on the most recent stable release because they
@@ -62,11 +107,4 @@ validate the output of the compiler diagnostics. The output can change between
 releases, so we pin to a specific release to avoid frequent and unexpected
 breakage.
 
-## Contributing
-
-We'd love your help with improving the documentation! Please feel free to
-[open issues](https://github.com/rust-lang/cargo/issues) about anything, and
-send in PRs for things you'd like to fix or change. If your change is large,
-please open an issue first, so we can make sure that it's something we'd
-accept before you go through the work of getting a PR together.
-
+[the SemVer chapter]: https://doc.rust-lang.org/nightly/cargo/reference/semver.html