add new documentation guidelines

docs/CODEOWNERS

@@ -35,11 +35,17 @@
 /client/sysinfo/ @koute
 /client/tracing/ @koute
 
+# Documentation audit
+/primitives/runtime @paritytech/DevRel/docs-audit
+/primitives/arithmetic @paritytech/DevRel/docs-audit
+# /primitives/core (to be added later)
+# /primitives/io (to be added later)
+
 # FRAME
-/frame/ @paritytech/frame-coders
-/frame/nfts/ @jsidorenko
+/frame/ @paritytech/frame-coders @paritytech/DevRel/docs-audit
+/frame/nfts/ @jsidorenko @paritytech/DevRel/docs-audit
 /frame/state-trie-migration/ @paritytech/frame-coders @cheme
-/frame/uniques/ @jsidorenko
+/frame/uniques/ @jsidorenko @paritytech/DevRel/docs-audit
 
 # GRANDPA, BABE, consensus stuff
 /client/consensus/babe/ @andresilva
@@ -57,12 +63,12 @@
 /primitives/merkle-mountain-range/ @acatangiu
 
 # Contracts
-/frame/contracts/ @athei
+/frame/contracts/ @athei @paritytech/DevRel/docs-audit
 
 # NPoS and election
-/frame/election-provider-multi-phase/ @paritytech/staking-core
-/frame/election-provider-support/ @paritytech/staking-core
-/frame/elections-phragmen/ @paritytech/staking-core
-/frame/nomination-pools/ @paritytech/staking-core
-/frame/staking/ @paritytech/staking-core
-/primitives/npos-elections/ @paritytech/staking-core
+/frame/election-provider-multi-phase/ @paritytech/staking-core @paritytech/DevRel/docs-audit
+/frame/election-provider-support/ @paritytech/staking-core @paritytech/DevRel/docs-audit
+/frame/elections-phragmen/ @paritytech/staking-core @paritytech/DevRel/docs-audit
+/frame/nomination-pools/ @paritytech/staking-core @paritytech/DevRel/docs-audit
+/frame/staking/ @paritytech/staking-core @paritytech/DevRel/docs-audit
+/primitives/npos-elections/ @paritytech/staking-core @paritytech/DevRel/docs-audit

docs/CONTRIBUTING.adoc

@@ -15,6 +15,7 @@ There are a few basic ground-rules for contributors (including the maintainer(s)
 . **All modifications** must be made in a **pull-request** to solicit feedback from other contributors.
 . A pull-request *must not be merged until CI* has finished successfully.
 . Contributors should adhere to the link:STYLE_GUIDE.md[house coding style].
+. Contributors should adhere to the link:DOCUMENTATION_GUIDELINES.md[house documenting style], when applicable.
 
 
 == Merge Process

docs/DOCUMENTATION_GUIDELINES.md

@@ -0,0 +1,227 @@
+# Substrate Documentation Guidelines
+
+This document is only focused on documenting parts of substrate that relates to its external API. The list of such crates can be found in [CODEOWNERS](./CODEOWNERS). Search for the crates that are auto-assigned to a team called `docs-audit`.
+
+These are crates that are often used by external developers and deserve a better documents. Consequently, most of this revolves around FRAME-development.
+
+- [Substrate Documentation Guidelines](#substrate-documentation-guidelines)
+  - [General/Non-Pallet Crates](#generalnon-pallet-crates)
+    - [What to Document?](#what-to-document)
+      - [Rust Docs vs. Code Comments](#rust-docs-vs-code-comments)
+    - [How to Document?](#how-to-document)
+    - [TLDR](#tldr)
+    - [Other Guidelines](#other-guidelines)
+      - [Document Through Code](#document-through-code)
+      - [Formatting Matters](#formatting-matters)
+  - [Pallet Crates](#pallet-crates)
+    - [Top Level Pallet Docs (`lib.rs`)](#top-level-pallet-docs-librs)
+    - [Dispatchable](#dispatchable)
+    - [Storage Items](#storage-items)
+
+
+## General/Non-Pallet Crates
+
+First, consider the case for all such crates, except for those that are pallets.
+
+### What to Document?
+
+The first question is, what should you document? Use the following filter:
+
+1. Within the set of crates above,
+2. Any `pub` item within them needs to be documented. If it is not `pub`, it won't show up in the rust-docs, and won't matter.
+    * Within `pub` items, sometimes they are only `pub` in order to be used by another internal crate, and you can foresee that this will not be used by anyone else other than you. These need **not** be documented thoroughly, and are left to your discretion to identify.
+    * Reminder: `trait` items are public by definition, if the trait is public.
+3. Of course, all of these crates should have a reasonable module documentation (`//!`).
+
+
+#### Rust Docs vs. Code Comments
+
+Note that anything starting with `///` is external rust-doc, and anything starting with `//` is just for you to see. Don't mix the two!
+
+```rust
+/// Computes the square root of the input, returning `Ok(_)` if successful.
+///
+/// # Errors
+/// ...
+///
+/// # Complexity
+/// ...
+///
+// Details about the complexity, how you implemented this, and some quirks that
+// are NOT relevant to the external interface, so it starts with '//'.
+// This can also be moved inside the function.
+pub fn sqrt(x: u32) -> Result<u32, ()> {
+    todo!();
+}
+
+```
+
+### How to Document?
+
+There are a few very good sources that you can look into:
+
+- https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html
+- https://web.mit.edu/rust-lang_v1.25/arch/amd64_ubuntu1404/share/doc/rust/html/book/first-edition/documentation.html
+- https://blog.guillaume-gomez.fr/articles/2020-03-12+Guide+on+how+to+write+documentation+for+a+Rust+crate
+
+
+As mentioned [here](https://web.mit.edu/rust-lang_v1.25/arch/amd64_ubuntu1404/share/doc/rust/html/book/first-edition/documentation.html#writing-documentation-comments) and [here](https://blog.guillaume-gomez.fr/articles/2020-03-12+Guide+on+how+to+write+documentation+for+a+Rust+crate), always start with a **single sentence** demonstrating what is being documented. If there is more to say, add it *after a newline*.
+
+About [special sections](https://web.mit.edu/rust-lang_v1.25/arch/amd64_ubuntu1404/share/doc/rust/html/book/first-edition/documentation.html#special-sections), we will most likely not need to think about panic and safety in any runtime related code. Our code is never `unsafe`, and will (almost) never panic.
+
+Use `# Example`s as much as possible. These are great ways to further demonstrate what your APIs are doing, and add free test coverage. As a cherry on top, any code in rust-docs is treated as an "integration tests", not unit tests, which tests your crate in a different way than unit tests. So, it is both a win for "more documentation" and a win for "more test coverage".
+
+You can also consider having am `# Error` section, but consider that optional. Of course, this only applies if there is a `Result` being returned, and IFF the `Error` variants are overly complicated.
+
+Strive to include correct links to other items in your written docs as much as possible. In other words, avoid \`some_func\` and instead use \[\`some_fund\`\]. Read more about how to correctly use links in your rust-docs [here](https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html#valid-links) and [here](https://rust-lang.github.io/rfcs/1946-intra-rustdoc-links.html#additions-to-the-documentation-syntax).
+
+> While you are linking, you might become conscious of the fact that you are in need of linking to (too many) foreign items in order to explain your API. This is leaning more towards API-Design rather than documentation, but it is a warning that the subject API might be slightly wrong. For example, most "glue" traits[^1] in `frame/support` should be designed, and documented without making hard assumptions about a particular pallets that implement them.
+
+### TLDR
+
+0. Have the goal of enforcing `#![deny(missing_docs)]` mentally, even if it is not enforced by the compiler 🙈.
+1. Start with a single, clear and concise sentence. Follow up with more context, after a newline, if needed.
+2. Use examples as much as reasonably possible.
+3. Use links as much as possible.
+4. Think about context. If you are in need of explaining a lot of foreign topics in documenting a trait that should not explicitly depend on them, you have likely not designed it properly.
+
+
+### Other Guidelines
+
+The above 5 guidelines must always be respected in docs, as long as reasonable possible.
+
+The following are a set of notes that may not necessarily hold at all circumstances. Consider them as opinionated guidelines that you may or may not abide by.
+
+
+#### Document Through Code
+
+You can certainly do parts of your documentation through your well-organized, properly-named code. That's all true, but:
+
+* This is hard to scale at a project the size of Polkadot/Substrate. Moreover, things like examples, errors and panics cannot be documented via just code.
+
+* Your written documents should *complement* the code, not *repeat* it. Put bluntly, if you end up writing this, you are likely doing it wrong:
+
+ ```rust
+ /// Sends request and handles the response.
+ trait SendRequestAndHandleResponse {
+
+ }
+ ```
+
+ Because the document is adding no extra information and you are better of without it.
+
+
+#### Formatting Matters
+
+The way you format your documents (newlines, heading and so on) do matter! Consider the below examples:
+
+```rust
+/// This function works with input u32 x and multiples it by two. If
+/// we optimize the other variant of it, we would be able to achieve more
+/// efficiency but I have to think about it. Probably can panic if the input
+/// overflows u32.
+fn multiply_by_2(x: u32) -> u32 { .. }
+```
+
+```rust
+/// Multiplies an input of type [`u32`] by two.
+///
+/// # Panics
+///
+/// Panics if the input overflows.
+///
+/// # Complexity
+///
+/// Is implemented using some algorithm that yields complexity of O(1).
+// More efficiency can be achieved if we improve this via such and such.
+fn multiply_by_2(x: u32) -> u32 { .. }
+```
+
+They are both roughly conveying the same set of facts, but one is substantially kinder on the eye. Especially for traits and type that you can foresee will be seen/used a lot, try and write the better version!
+
+Similarly, make sure your comments are wrapped at 100 characters line-width (as defined by our [`rustfmt.toml`](../rustfmt.toml)), no **more and no less**! The more is fixed by `rustfmt` and our CI, but if you (some some unknown reason) wrap your lines at 59 characters, it will pass the CI, and it will not look good 🫣.
+
+[^1]: Those that help two pallets talk to each other.
+
+## Pallet Crates
+
+Everything above is related to non-pallet details. They might be relevant in both crates that are pallets, and non-pallet crates.
+
+The following is relevant to how to document parts of a crate that is a pallet.
+
+### Top Level Pallet Docs (`lib.rs`)
+
+for the top-level pallet docs, consider the following template:
+
+```
+//! # <Pallet Name>
+//!
+//! <single-liner about the pallet>.
+//!
+//! ## High-Level/End-User Details
+//!
+//! <a few paragraphs, focus on what external folks should know about the pallet>
+//!
+//! <The audience here is potentially non-coders who just want to know what this pallet does, not how it does it>
+//!
+//! ### Example
+//!
+//! <Your pallet must have a few tests that cover important user journeys. Use https://crates.io/crates/docify to reuse your these as examples>.
+//!
+//! ## Code Details
+//!
+//! <inside [`pallet`] module, a template is auto-generated that leads the reader to the relevant items. This is just a reminder to navigate to that page. Don't repeat things like "See Config trait for ..." that are generated inside [`pallet`] in here>
+//!
+//! See [`pallet`] module.
+//!
+//! <The audience of this is those who want to know how this pallet works, to the extent of being able to build something on top of it, like a DApp or another pallet>
+//!
+//! ## Low Level / Implementation Details
+//!
+//! <The format of this section is up to you, but we suggest the Design-oriented approach that follows>
+//!
+//! <The audience of this would be your future self, and those who want to deeply understand the pallet to optimize it further and such>
+//!
+//! ### Design Goals (optional)
+//!
+//! <Describe your goals with with the pallet design.>
+//!
+//! ### Design (optional)
+//!
+//! <Describe how you reach those goals. This should namely describe how your storage is laid out.>
+//!
+//! ### Terminology (optional)
+//!
+//! <Optionally, contain any custom terminology here. You can link to it if you want to use the terminology further up>
+```
+
+### Dispatchable
+
+For each dispatchable (`fn` item inside `pallet::call`), consider the following template:
+
+```
+/// <One liner explaining what this does>
+///
+/// ## Dispatch Origin
+///
+/// The dispatch origin of this call must be <details>
+///
+/// ## Details
+///
+/// <All other details. Focus on what errors could occur within this dispatch>
+///
+/// ## Errors (optional)
+///
+/// <If an extensive list of errors can be returned, list them individually instead of mentioning them in the section above>
+///
+/// ## Events (optional)
+///
+/// <Events are akin to the "return type" of dispatchables, optionally mention them>
+pub fn name(origin: OriginFor<T>, ...) -> DispatchResult {}
+```
+
+### Storage Items
+
+1. If a map-like type is being used, always note the choice of your hashers as private code docs (`// Hasher X chosen because ...`). Recall that this is not relevant information to external people, so it must be documented as `//`.
+2. Consider explaining why a storage type is always bounded.
+3. Consider explaining the crypto-economics of how a deposit is being taken in return of the storage being used.

docs/PULL_REQUEST_TEMPLATE.md

@@ -18,12 +18,11 @@ Before you submit, please check that:
   - [ ] Github project assignment
 - [ ] **Related Issues:** You mentioned a related issue if this PR is related to it, e.g. `Fixes #228` or `Related #1337`.
 - [ ] **2 Reviewers:** You asked at least two reviewers to review. If you aren't sure, start with GH suggestions.
-- [ ] **Style Guide:** Your PR adheres to [the style guide](https://github.com/paritytech/substrate/blob/master/docs/STYLE_GUIDE.md)
+- [ ] **Style Guide:** Your PR adheres to [the style guide](https://github.com/paritytech/substrate/blob/master/docs/STYLE_GUIDE.md).
   - In particular, mind the maximal line length of 100 (120 in exceptional circumstances).
   - There is no commented code checked in unless necessary.
   - Any panickers in the runtime have a proof or were removed.
-- [ ] **Runtime Version:** You bumped the runtime version if there are breaking changes in the **runtime**.
-- [ ] **Docs:** You updated any rustdocs which may need to change.
+- [ ] **Docs:** You updated any rustdocs which may need to change, as described [here](https://github.com/paritytech/substrate/blob/master/docs/DOCUMENTATION_GUIDELINES.md).
 - [ ] **Polkadot Companion:** Has the PR altered the external API or interfaces used by Polkadot?
   - [ ] If so, do you have the corresponding Polkadot PR ready?
   - [ ] Optionally: Do you have a corresponding Cumulus PR?