From 2bfe4bad59080fdbe9201b00a4585c60e91b0bdb Mon Sep 17 00:00:00 2001
From: kianenigma <kian@parity.io>
Date: Wed, 10 May 2023 12:11:17 +0200
Subject: [PATCH 01/18] add new documentation style-guides

---
 docs/CONTRIBUTING.adoc           |   1 +
 docs/DOCUMENTATION_GUIDELINES.md | 227 +++++++++++++++++++++++++++++++
 docs/PULL_REQUEST_TEMPLATE.md    |   5 +-
 3 files changed, 230 insertions(+), 3 deletions(-)
 create mode 100644 docs/DOCUMENTATION_GUIDELINES.md

diff --git a/docs/CONTRIBUTING.adoc b/docs/CONTRIBUTING.adoc
index 759141a62dfc7..89b97c7f481a5 100644
--- a/docs/CONTRIBUTING.adoc
+++ b/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:STYLE_GUIDE.md[house documenting style], when applicable.
 
 
 == Merge Process
diff --git a/docs/DOCUMENTATION_GUIDELINES.md b/docs/DOCUMENTATION_GUIDELINES.md
new file mode 100644
index 0000000000000..f724ab9840d2f
--- /dev/null
+++ b/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.
diff --git a/docs/PULL_REQUEST_TEMPLATE.md b/docs/PULL_REQUEST_TEMPLATE.md
index 12f39371892e7..f6d74ff24cc36 100644
--- a/docs/PULL_REQUEST_TEMPLATE.md
+++ b/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?

From 29ded796a6ca96111707aa250e7866a1a4221a4e Mon Sep 17 00:00:00 2001
From: kianenigma <kian@parity.io>
Date: Wed, 10 May 2023 12:23:27 +0200
Subject: [PATCH 02/18] update CODEOWNERS as well

---
 docs/CODEOWNERS | 26 ++++++++++++++++----------
 1 file changed, 16 insertions(+), 10 deletions(-)

diff --git a/docs/CODEOWNERS b/docs/CODEOWNERS
index 0f45a593de0ae..63294d90e9d06 100644
--- a/docs/CODEOWNERS
+++ b/docs/CODEOWNERS
@@ -35,11 +35,17 @@
 /client/sysinfo/ @koute
 /client/tracing/ @koute
 
+# Documentation audit
+/primitives/runtime @paritytech/docs-audit
+/primitives/arithmetic @paritytech/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/docs-audit
+/frame/nfts/ @jsidorenko @paritytech/docs-audit
 /frame/state-trie-migration/ @paritytech/frame-coders @cheme
-/frame/uniques/ @jsidorenko
+/frame/uniques/ @jsidorenko @paritytech/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/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/docs-audit
+/frame/election-provider-support/ @paritytech/staking-core @paritytech/docs-audit
+/frame/elections-phragmen/ @paritytech/staking-core @paritytech/docs-audit
+/frame/nomination-pools/ @paritytech/staking-core @paritytech/docs-audit
+/frame/staking/ @paritytech/staking-core @paritytech/docs-audit
+/primitives/npos-elections/ @paritytech/staking-core @paritytech/docs-audit

From 4392e1a2380618810fcab6d789cf075d98d20b0e Mon Sep 17 00:00:00 2001
From: kianenigma <kian@parity.io>
Date: Wed, 10 May 2023 12:36:15 +0200
Subject: [PATCH 03/18] try new team

---
 docs/CODEOWNERS        | 24 ++++++++++++------------
 docs/CONTRIBUTING.adoc |  2 +-
 2 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/docs/CODEOWNERS b/docs/CODEOWNERS
index 63294d90e9d06..7c4046bad6bf6 100644
--- a/docs/CODEOWNERS
+++ b/docs/CODEOWNERS
@@ -36,16 +36,16 @@
 /client/tracing/ @koute
 
 # Documentation audit
-/primitives/runtime @paritytech/docs-audit
-/primitives/arithmetic @paritytech/docs-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 @paritytech/docs-audit
-/frame/nfts/ @jsidorenko @paritytech/docs-audit
+/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 @paritytech/docs-audit
+/frame/uniques/ @jsidorenko @paritytech/DevRel/docs-audit
 
 # GRANDPA, BABE, consensus stuff
 /client/consensus/babe/ @andresilva
@@ -63,12 +63,12 @@
 /primitives/merkle-mountain-range/ @acatangiu
 
 # Contracts
-/frame/contracts/ @athei @paritytech/docs-audit
+/frame/contracts/ @athei @paritytech/DevRel/docs-audit
 
 # NPoS and election
-/frame/election-provider-multi-phase/ @paritytech/staking-core @paritytech/docs-audit
-/frame/election-provider-support/ @paritytech/staking-core @paritytech/docs-audit
-/frame/elections-phragmen/ @paritytech/staking-core @paritytech/docs-audit
-/frame/nomination-pools/ @paritytech/staking-core @paritytech/docs-audit
-/frame/staking/ @paritytech/staking-core @paritytech/docs-audit
-/primitives/npos-elections/ @paritytech/staking-core @paritytech/docs-audit
+/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
diff --git a/docs/CONTRIBUTING.adoc b/docs/CONTRIBUTING.adoc
index 89b97c7f481a5..dd1a77015d004 100644
--- a/docs/CONTRIBUTING.adoc
+++ b/docs/CONTRIBUTING.adoc
@@ -15,7 +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:STYLE_GUIDE.md[house documenting style], when applicable.
+. Contributors should adhere to the link:DOCUMENTATION_GUIDELINES.md[house documenting style], when applicable.
 
 
 == Merge Process

From a02795bbbe268937a3ee9837c2f921169a4147c6 Mon Sep 17 00:00:00 2001
From: kianenigma <kian@parity.io>
Date: Wed, 10 May 2023 12:40:50 +0200
Subject: [PATCH 04/18] revert

---
 docs/CODEOWNERS | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/docs/CODEOWNERS b/docs/CODEOWNERS
index 7c4046bad6bf6..63294d90e9d06 100644
--- a/docs/CODEOWNERS
+++ b/docs/CODEOWNERS
@@ -36,16 +36,16 @@
 /client/tracing/ @koute
 
 # Documentation audit
-/primitives/runtime @paritytech/DevRel/docs-audit
-/primitives/arithmetic @paritytech/DevRel/docs-audit
+/primitives/runtime @paritytech/docs-audit
+/primitives/arithmetic @paritytech/docs-audit
 # /primitives/core (to be added later)
 # /primitives/io (to be added later)
 
 # FRAME
-/frame/ @paritytech/frame-coders @paritytech/DevRel/docs-audit
-/frame/nfts/ @jsidorenko @paritytech/DevRel/docs-audit
+/frame/ @paritytech/frame-coders @paritytech/docs-audit
+/frame/nfts/ @jsidorenko @paritytech/docs-audit
 /frame/state-trie-migration/ @paritytech/frame-coders @cheme
-/frame/uniques/ @jsidorenko @paritytech/DevRel/docs-audit
+/frame/uniques/ @jsidorenko @paritytech/docs-audit
 
 # GRANDPA, BABE, consensus stuff
 /client/consensus/babe/ @andresilva
@@ -63,12 +63,12 @@
 /primitives/merkle-mountain-range/ @acatangiu
 
 # Contracts
-/frame/contracts/ @athei @paritytech/DevRel/docs-audit
+/frame/contracts/ @athei @paritytech/docs-audit
 
 # NPoS and election
-/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
+/frame/election-provider-multi-phase/ @paritytech/staking-core @paritytech/docs-audit
+/frame/election-provider-support/ @paritytech/staking-core @paritytech/docs-audit
+/frame/elections-phragmen/ @paritytech/staking-core @paritytech/docs-audit
+/frame/nomination-pools/ @paritytech/staking-core @paritytech/docs-audit
+/frame/staking/ @paritytech/staking-core @paritytech/docs-audit
+/primitives/npos-elections/ @paritytech/staking-core @paritytech/docs-audit

From 0674e9c2fce230f1a931e92e40b4fa2f22d4d52d Mon Sep 17 00:00:00 2001
From: Kian Paimani <5588131+kianenigma@users.noreply.github.com>
Date: Wed, 17 May 2023 22:21:38 +0200
Subject: [PATCH 05/18] Update docs/DOCUMENTATION_GUIDELINES.md

Co-authored-by: Juan <juangirini@gmail.com>
---
 docs/DOCUMENTATION_GUIDELINES.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/DOCUMENTATION_GUIDELINES.md b/docs/DOCUMENTATION_GUIDELINES.md
index f724ab9840d2f..e0c49a994655b 100644
--- a/docs/DOCUMENTATION_GUIDELINES.md
+++ b/docs/DOCUMENTATION_GUIDELINES.md
@@ -116,7 +116,7 @@ You can certainly do parts of your documentation through your well-organized, pr
 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
+/// This function works with input u32 x and multiplies 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.

From 184d5daade90f0d692e17fed56609cd340329064 Mon Sep 17 00:00:00 2001
From: Kian Paimani <5588131+kianenigma@users.noreply.github.com>
Date: Wed, 17 May 2023 22:21:55 +0200
Subject: [PATCH 06/18] Update docs/DOCUMENTATION_GUIDELINES.md

Co-authored-by: Juan <juangirini@gmail.com>
---
 docs/DOCUMENTATION_GUIDELINES.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/DOCUMENTATION_GUIDELINES.md b/docs/DOCUMENTATION_GUIDELINES.md
index e0c49a994655b..4cc74a748c157 100644
--- a/docs/DOCUMENTATION_GUIDELINES.md
+++ b/docs/DOCUMENTATION_GUIDELINES.md
@@ -151,7 +151,7 @@ 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:
+For the top-level pallet docs, consider the following template:
 
 ```
 //! # <Pallet Name>

From 6ae9c3c5d494b04fdbe2f1279728d3182a0fdcc9 Mon Sep 17 00:00:00 2001
From: Kian Paimani <5588131+kianenigma@users.noreply.github.com>
Date: Tue, 23 May 2023 08:35:25 +0200
Subject: [PATCH 07/18] Apply suggestions from code review

Co-authored-by: Ben Greenberg <13892277+hummusonrails@users.noreply.github.com>
---
 docs/DOCUMENTATION_GUIDELINES.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/DOCUMENTATION_GUIDELINES.md b/docs/DOCUMENTATION_GUIDELINES.md
index 4cc74a748c157..5a16a888aa965 100644
--- a/docs/DOCUMENTATION_GUIDELINES.md
+++ b/docs/DOCUMENTATION_GUIDELINES.md
@@ -2,7 +2,7 @@
 
 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.
+These are crates that are often used by external developers and need more thorough documentation. These are the crates most concerned with FRAME development.
 
 - [Substrate Documentation Guidelines](#substrate-documentation-guidelines)
   - [General/Non-Pallet Crates](#generalnon-pallet-crates)
@@ -28,15 +28,15 @@ First, consider the case for all such crates, except for those that are pallets.
 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.
+2. All `pub` item within the aforementioned crates need to be documented. If it is not `pub`, it does not appear in the rust-docs, and is not public facing.
     * 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 (`//!`).
+3. All public modules (`mod`) should have reasonable module-level 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!
+Note that anything starting with `///` is an external rust-doc, and everything starting with `//` does not appear in the rust-docs. It's important to not confuse the two in your documentation.
 
 ```rust
 /// Computes the square root of the input, returning `Ok(_)` if successful.

From 29ed2d01b72193b4df2e0afb36eca7a9fb246cfc Mon Sep 17 00:00:00 2001
From: Kian Paimani <5588131+kianenigma@users.noreply.github.com>
Date: Tue, 23 May 2023 08:43:16 +0200
Subject: [PATCH 08/18] Apply suggestions from code review

Co-authored-by: Sam Johnson <sam@durosoft.com>
Co-authored-by: Ben Greenberg <13892277+hummusonrails@users.noreply.github.com>
---
 docs/DOCUMENTATION_GUIDELINES.md | 19 +++++++++----------
 1 file changed, 9 insertions(+), 10 deletions(-)

diff --git a/docs/DOCUMENTATION_GUIDELINES.md b/docs/DOCUMENTATION_GUIDELINES.md
index 5a16a888aa965..4d1f52db7c8ab 100644
--- a/docs/DOCUMENTATION_GUIDELINES.md
+++ b/docs/DOCUMENTATION_GUIDELINES.md
@@ -44,9 +44,6 @@ Note that anything starting with `///` is an external rust-doc, and everything s
 /// # 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.
@@ -65,17 +62,17 @@ There are a few very good sources that you can look into:
 - 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*.
+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. All additional documentation should be added *after a newline*. Strive to make the first sentence succinct and short. The reason for this is the first paragraph of docs about an item (everything before the first newline) is used as the excerpt that rust doc displays about this item when it appears in tables, such as the table listing all functions in a module. If this excerpt is too long, the module docs will be very difficult to read.
 
 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".
+Use `# Examples as much as possible. These are great ways to further demonstrate what your APIs are doing, and add free test coverage. As an additional benefit, 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.
+You can also consider having an `# Error` section optionally. Of course, this only applies if there is a `Result` being returned, and if 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.
+> 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 particular pallets that implement them.
 
 ### TLDR
 
@@ -88,14 +85,16 @@ Strive to include correct links to other items in your written docs as much as p
 
 ### Other Guidelines
 
-The above 5 guidelines must always be respected in docs, as long as reasonable possible.
+The above five guidelines must always be reasonably respected in the documentation.
 
-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.
+The following are a set of notes that may not necessarily hold in all circumstances:
 
 
 #### Document Through Code
 
-You can certainly do parts of your documentation through your well-organized, properly-named code. That's all true, but:
+You should make sure that your code is properly-named and well-organized so that your code functions as a form of documentation. However, within the complexity of our projects in Polkadot/Substrate that is not enough. Particularly, things like examples, errors and panics cannot be documented only through properly-named and well-organized code.
+
+> Our north star is self-documenting code that also happens to be well-documented and littered with examples.
 
 * 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.
 

From 160f32e709b04e811cc569b1c1b81068d5147e23 Mon Sep 17 00:00:00 2001
From: Kian Paimani <5588131+kianenigma@users.noreply.github.com>
Date: Tue, 23 May 2023 08:44:35 +0200
Subject: [PATCH 09/18] Update docs/DOCUMENTATION_GUIDELINES.md

---
 docs/DOCUMENTATION_GUIDELINES.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/DOCUMENTATION_GUIDELINES.md b/docs/DOCUMENTATION_GUIDELINES.md
index 4d1f52db7c8ab..b68d181509b28 100644
--- a/docs/DOCUMENTATION_GUIDELINES.md
+++ b/docs/DOCUMENTATION_GUIDELINES.md
@@ -96,7 +96,6 @@ You should make sure that your code is properly-named and well-organized so that
 
 > Our north star is self-documenting code that also happens to be well-documented and littered with examples.
 
-* 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:
 

From ac3f6e01ff9e3fd88fa847963f2801139c615542 Mon Sep 17 00:00:00 2001
From: Kian Paimani <5588131+kianenigma@users.noreply.github.com>
Date: Tue, 23 May 2023 09:38:55 +0200
Subject: [PATCH 10/18] Apply suggestions from code review

Co-authored-by: Liam Aharon <liam.aharon@hotmail.com>
Co-authored-by: Ben Greenberg <13892277+hummusonrails@users.noreply.github.com>
---
 docs/DOCUMENTATION_GUIDELINES.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/DOCUMENTATION_GUIDELINES.md b/docs/DOCUMENTATION_GUIDELINES.md
index b68d181509b28..c06128b001090 100644
--- a/docs/DOCUMENTATION_GUIDELINES.md
+++ b/docs/DOCUMENTATION_GUIDELINES.md
@@ -80,7 +80,7 @@ Strive to include correct links to other items in your written docs as much as p
 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.
+4. Think about context. If you are explaining a lot of foreign topics while documenting a trait that should not explicitly depend on them, you have likely not designed it properly.
 
 
 ### Other Guidelines
@@ -97,7 +97,7 @@ You should make sure that your code is properly-named and well-organized so that
 > Our north star is self-documenting code that also happens to be well-documented and littered with examples.
 
 
-* Your written documents should *complement* the code, not *repeat* it. Put bluntly, if you end up writing this, you are likely doing it wrong:
+* Your written documents should *complement* the code, not *repeat* it. As an example, a documentation on top of a code example should never look like the following:
 
  ```rust
  /// Sends request and handles the response.
@@ -106,7 +106,7 @@ You should make sure that your code is properly-named and well-organized so that
  }
  ```
 
- Because the document is adding no extra information and you are better of without it.
+In the above example, the documentation has added no useful information not already contained within the properly-named trait and is redundant. 
 
 
 #### Formatting Matters

From 23b85959412daaf6b1e023ddd760c3de08dc2024 Mon Sep 17 00:00:00 2001
From: Kian Paimani <5588131+kianenigma@users.noreply.github.com>
Date: Tue, 23 May 2023 09:40:32 +0200
Subject: [PATCH 11/18] Apply suggestions from code review

Co-authored-by: Ben Greenberg <13892277+hummusonrails@users.noreply.github.com>
Co-authored-by: Liam Aharon <liam.aharon@hotmail.com>
---
 docs/DOCUMENTATION_GUIDELINES.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/DOCUMENTATION_GUIDELINES.md b/docs/DOCUMENTATION_GUIDELINES.md
index c06128b001090..efcc918e0802c 100644
--- a/docs/DOCUMENTATION_GUIDELINES.md
+++ b/docs/DOCUMENTATION_GUIDELINES.md
@@ -111,7 +111,7 @@ In the above example, the documentation has added no useful information not alre
 
 #### Formatting Matters
 
-The way you format your documents (newlines, heading and so on) do matter! Consider the below examples:
+The way you format your documents (newlines, heading and so on) makes a difference. Consider the below examples:
 
 ```rust
 /// This function works with input u32 x and multiplies it by two. If
@@ -135,15 +135,15 @@ fn multiply_by_2(x: u32) -> u32 { .. }
 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!
+They are both roughly conveying the same set of facts, but one is easier to follow because it was formatted cleanly. Especially for traits and types that you can foresee will be seen and used a lot, try and write a well formatted 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 🫣.
+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 (for 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 guidelines so far have been general in nature, and are applicable to crates that are pallets and crates that're not pallets.
 
 The following is relevant to how to document parts of a crate that is a pallet.
 

From 073aae9b737f8d81830fd33a31ce28bd929f83a7 Mon Sep 17 00:00:00 2001
From: Kian Paimani <5588131+kianenigma@users.noreply.github.com>
Date: Tue, 23 May 2023 09:47:46 +0200
Subject: [PATCH 12/18] Apply suggestions from code review

Co-authored-by: Sacha Lansky <sacha@parity.io>
Co-authored-by: Liam Aharon <liam.aharon@hotmail.com>
---
 docs/DOCUMENTATION_GUIDELINES.md | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/docs/DOCUMENTATION_GUIDELINES.md b/docs/DOCUMENTATION_GUIDELINES.md
index efcc918e0802c..457218b38958f 100644
--- a/docs/DOCUMENTATION_GUIDELINES.md
+++ b/docs/DOCUMENTATION_GUIDELINES.md
@@ -164,11 +164,11 @@ For the top-level pallet docs, consider the following template:
 //!
 //! ### 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>.
+//! <Your pallet must have a few tests that cover important user journeys. Use https://crates.io/crates/docify to reuse 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>
+//! <Reminder: inside the [`pallet`] module, a template that leads the reader to the relevant items is auto-generated. There is no need to repeat things like "See Config trait for ...", which are generated inside [`pallet`] here anyways>
 //!
 //! See [`pallet`] module.
 //!
@@ -178,19 +178,19 @@ For the top-level pallet docs, consider the following template:
 //!
 //! <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>
+//! <The audience of this would be your future self, or anyone who wants to gain a deep understanding of how the pallet works so that they can eventually propose optimizations to it>
 //!
 //! ### Design Goals (optional)
 //!
-//! <Describe your goals with with the pallet design.>
+//! <Describe your goals with the pallet design.>
 //!
 //! ### Design (optional)
 //!
-//! <Describe how you reach those goals. This should namely describe how your storage is laid out.>
+//! <Describe how you've reached those goals. This should describe the storage layout of your pallet and what was your approach in designing it that way.>
 //!
 //! ### Terminology (optional)
 //!
-//! <Optionally, contain any custom terminology here. You can link to it if you want to use the terminology further up>
+//! <Optionally, explain any non-obvious terminology here. You can link to it if you want to use the terminology further up>
 ```
 
 ### Dispatchable
@@ -198,15 +198,15 @@ For the top-level pallet docs, consider the following template:
 For each dispatchable (`fn` item inside `pallet::call`), consider the following template:
 
 ```
-/// <One liner explaining what this does>
+/// <One-liner explaining what the dispatchable does>
 ///
 /// ## Dispatch Origin
 ///
-/// The dispatch origin of this call must be <details>
+/// The dispatch origin of this call must be <details (e.g. Root, Signed, Unsigned)>
 ///
 /// ## Details
 ///
-/// <All other details. Focus on what errors could occur within this dispatch>
+/// <All other details, namely any errors that could occur within this dispatch and the events this dispatch could emit>
 ///
 /// ## Errors (optional)
 ///
@@ -215,7 +215,7 @@ For each dispatchable (`fn` item inside `pallet::call`), consider the following
 /// ## Events (optional)
 ///
 /// <Events are akin to the "return type" of dispatchables, optionally mention them>
-pub fn name(origin: OriginFor<T>, ...) -> DispatchResult {}
+pub fn name_of_dispatchable(origin: OriginFor<T>, ...) -> DispatchResult {}
 ```
 
 ### Storage Items

From 2f71f64c8d724f6d3b2b889f16364233d2394b79 Mon Sep 17 00:00:00 2001
From: Kian Paimani <5588131+kianenigma@users.noreply.github.com>
Date: Tue, 23 May 2023 09:58:37 +0200
Subject: [PATCH 13/18] Further updates.

---
 docs/DOCUMENTATION_GUIDELINES.md | 20 ++++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

diff --git a/docs/DOCUMENTATION_GUIDELINES.md b/docs/DOCUMENTATION_GUIDELINES.md
index 457218b38958f..9f8f9c4327a85 100644
--- a/docs/DOCUMENTATION_GUIDELINES.md
+++ b/docs/DOCUMENTATION_GUIDELINES.md
@@ -27,8 +27,8 @@ First, consider the case for all such crates, except for those that are pallets.
 
 The first question is, what should you document? Use the following filter:
 
-1. Within the set of crates above,
-2. All `pub` item within the aforementioned crates need to be documented. If it is not `pub`, it does not appear in the rust-docs, and is not public facing.
+1. In the crates assigned to `docs-audit` in [CODEOWNERS](./CODEOWNERS),
+2. All `pub` item need to be documented. If it is not `pub`, it does not appear in the rust-docs, and is not public facing.
     * 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. All public modules (`mod`) should have reasonable module-level documentation (`//!`).
@@ -50,7 +50,6 @@ Note that anything starting with `///` is an external rust-doc, and everything s
 pub fn sqrt(x: u32) -> Result<u32, ()> {
     todo!();
 }
-
 ```
 
 ### How to Document?
@@ -61,7 +60,6 @@ There are a few very good sources that you can look into:
 - 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. All additional documentation should be added *after a newline*. Strive to make the first sentence succinct and short. The reason for this is the first paragraph of docs about an item (everything before the first newline) is used as the excerpt that rust doc displays about this item when it appears in tables, such as the table listing all functions in a module. If this excerpt is too long, the module docs will be very difficult to read.
 
 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.
@@ -71,10 +69,12 @@ Use `# Examples as much as possible. These are great ways to further demonstrate
 You can also consider having an `# Error` section optionally. Of course, this only applies if there is a `Result` being returned, and if 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).
+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_func`]``.
+
 
 > 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 particular pallets that implement them.
 
-### TLDR
+#### 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.
@@ -82,6 +82,10 @@ Strive to include correct links to other items in your written docs as much as p
 3. Use links as much as possible.
 4. Think about context. If you are explaining a lot of foreign topics while documenting a trait that should not explicitly depend on them, you have likely not designed it properly.
 
+#### Proc-Macros
+
+Note that there are special considerations when documenting proc macros. Doc links will appear to function _within_ your proc macro crate, but often will no longer function when these proc macros are re-exported elsewhere in your project. The exception is doc links to _other proc macros_ which will function just fine if they are also being re-exported. It is also often necessary to disambiguate between a proc macro and a function of the same name, which can be done using the `macro@my_macro_name` syntax in your link. 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).
+
 
 ### Other Guidelines
 
@@ -106,7 +110,7 @@ You should make sure that your code is properly-named and well-organized so that
  }
  ```
 
-In the above example, the documentation has added no useful information not already contained within the properly-named trait and is redundant. 
+In the above example, the documentation has added no useful information not already contained within the properly-named trait and is redundant.
 
 
 #### Formatting Matters
@@ -168,9 +172,9 @@ For the top-level pallet docs, consider the following template:
 //!
 //! ## Code Details
 //!
-//! <Reminder: inside the [`pallet`] module, a template that leads the reader to the relevant items is auto-generated. There is no need to repeat things like "See Config trait for ...", which are generated inside [`pallet`] here anyways>
+//! <Reminder: inside the [`pallet`] module, a template that leads the reader to the relevant items is auto-generated. There is no need to repeat things like "See Config trait for ...", which are generated inside [`pallet`] here anyways. You can use the below line as-is:>
 //!
-//! See [`pallet`] module.
+//! See the [`pallet`] module for more information about the interfaces this pallet exposes, including its configuration trait, dispatchables, events and errors.
 //!
 //! <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>
 //!

From 8855ad12a674be831d9a654941c50586a8e9665b Mon Sep 17 00:00:00 2001
From: Kian Paimani <5588131+kianenigma@users.noreply.github.com>
Date: Tue, 23 May 2023 10:01:42 +0200
Subject: [PATCH 14/18] note about rewrap.

---
 docs/DOCUMENTATION_GUIDELINES.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/DOCUMENTATION_GUIDELINES.md b/docs/DOCUMENTATION_GUIDELINES.md
index 9f8f9c4327a85..0af80e3eedc6e 100644
--- a/docs/DOCUMENTATION_GUIDELINES.md
+++ b/docs/DOCUMENTATION_GUIDELINES.md
@@ -1,4 +1,4 @@
-# Substrate Documentation Guidelines
+wra# 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`.
 
@@ -141,7 +141,7 @@ fn multiply_by_2(x: u32) -> u32 { .. }
 
 They are both roughly conveying the same set of facts, but one is easier to follow because it was formatted cleanly. Especially for traits and types that you can foresee will be seen and used a lot, try and write a well formatted 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 (for some unknown reason) wrap your lines at 59 characters, it will pass the CI, and it will not look good 🫣.
+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 (for some unknown reason) wrap your lines at 59 characters, it will pass the CI, and it will not look good 🫣. Consider using a plugin like [rewrap](https://marketplace.visualstudio.com/items?itemName=stkb.rewrap) (for Visual Studio Code) to properly do this.
 
 [^1]: Those that help two pallets talk to each other.
 

From 55d8872bf270f1e7b57b184fd0c67de35b2e5d44 Mon Sep 17 00:00:00 2001
From: kianenigma <kian@parity.io>
Date: Tue, 23 May 2023 10:18:09 +0200
Subject: [PATCH 15/18] update ToC and more

---
 docs/DOCUMENTATION_GUIDELINES.md | 59 +++++++++++++++++++++++---------
 1 file changed, 42 insertions(+), 17 deletions(-)

diff --git a/docs/DOCUMENTATION_GUIDELINES.md b/docs/DOCUMENTATION_GUIDELINES.md
index 0af80e3eedc6e..c5eadc44d96ad 100644
--- a/docs/DOCUMENTATION_GUIDELINES.md
+++ b/docs/DOCUMENTATION_GUIDELINES.md
@@ -4,19 +4,19 @@ This document is only focused on documenting parts of substrate that relates to
 
 These are crates that are often used by external developers and need more thorough documentation. These are the crates most concerned with 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)
+- [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)
+    - [Proc-Macros](#proc-macros)
+  - [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
@@ -149,7 +149,7 @@ Similarly, make sure your comments are wrapped at 100 characters line-width (as
 
 The guidelines so far have been general in nature, and are applicable to crates that are pallets and crates that're not pallets.
 
-The following is relevant to how to document parts of a crate that is a pallet.
+The following is relevant to how to document parts of a crate that is a pallet. See [`pallet-fast-unstake`](../frame/fast-unstake/src/lib.rs) as one examples of adhering these guidelines.
 
 ### Top Level Pallet Docs (`lib.rs`)
 
@@ -160,24 +160,28 @@ For the top-level pallet docs, consider the following template:
 //!
 //! <single-liner about the pallet>.
 //!
-//! ## High-Level/End-User Details
+//! ## Overview
 //!
-//! <a few paragraphs, focus on what external folks should know about the pallet>
+//! <should be high-level details that are relevant to the most broad audience>
 //!
 //! <The audience here is potentially non-coders who just want to know what this pallet does, not how it does it>
 //!
+//! <potentially a few paragraphs, focus on what external folks should know about the pallet>
+//!
 //! ### Example
 //!
 //! <Your pallet must have a few tests that cover important user journeys. Use https://crates.io/crates/docify to reuse these as examples>.
 //!
-//! ## Code Details
+//! ## Pallet API
 //!
 //! <Reminder: inside the [`pallet`] module, a template that leads the reader to the relevant items is auto-generated. There is no need to repeat things like "See Config trait for ...", which are generated inside [`pallet`] here anyways. You can use the below line as-is:>
 //!
-//! See the [`pallet`] module for more information about the interfaces this pallet exposes, including its configuration trait, dispatchables, events and errors.
+//! See the [`pallet`] module for more information about the interfaces this pallet exposes, including its configuration trait, dispatchables, storage items, events and errors.
 //!
 //! <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>
 //!
+//! This section can most often be left as-is.
+//!
 //! ## Low Level / Implementation Details
 //!
 //! <The format of this section is up to you, but we suggest the Design-oriented approach that follows>
@@ -197,6 +201,27 @@ For the top-level pallet docs, consider the following template:
 //! <Optionally, explain any non-obvious terminology here. You can link to it if you want to use the terminology further up>
 ```
 
+This template's details (heading 3s and beyond) are left flexible, and at the discretion of the developer to make the best final choice about. For example, you might want to include `### Terminology` or not. Moreover, you might find it more useful to include it in `## Overview`.
+
+Nonetheless, the high level flow of going from the most high level explanation to the most low level explanation is important to follow.
+
+As a rule of thumb, the Heading 2s (`##`) in this template can be considered a strict rule, while the Heading 3s (`###`) and beyond are flexible.
+
+#### Polkadot and Substrate
+
+Optionally, in order to demonstrate the relation between the two, you can start the pallet documentation with:
+
+```
+//! > Made with *Substrate*, for *Polkadot*.
+//!
+//! [![github]](https://github.com/paritytech/substrate/frame/fast-unstake) -
+//! [![polkadot]](https://polkadot.network)
+//!
+//! [polkadot]: https://img.shields.io/badge/polkadot-E6007A?style=for-the-badge&logo=polkadot&logoColor=white
+//! [github]: https://img.shields.io/badge/github-8da0cb?style=for-the-badge&labelColor=555555&logo=github
+
+```
+
 ### Dispatchable
 
 For each dispatchable (`fn` item inside `pallet::call`), consider the following template:

From 401e171feb9ce55998899485b236ba57a0b2e1fb Mon Sep 17 00:00:00 2001
From: kianenigma <kian@parity.io>
Date: Tue, 23 May 2023 10:20:00 +0200
Subject: [PATCH 16/18] update ToC and more

---
 docs/DOCUMENTATION_GUIDELINES.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/DOCUMENTATION_GUIDELINES.md b/docs/DOCUMENTATION_GUIDELINES.md
index c5eadc44d96ad..ff3d497df4bdc 100644
--- a/docs/DOCUMENTATION_GUIDELINES.md
+++ b/docs/DOCUMENTATION_GUIDELINES.md
@@ -15,6 +15,7 @@ These are crates that are often used by external developers and need more thorou
     - [Formatting Matters](#formatting-matters)
 - [Pallet Crates](#pallet-crates)
   - [Top Level Pallet Docs (`lib.rs`)](#top-level-pallet-docs-librs)
+    - [Polkadot and Substrate](#polkadot-and-substrate)
   - [Dispatchable](#dispatchable)
   - [Storage Items](#storage-items)
 
@@ -219,7 +220,6 @@ Optionally, in order to demonstrate the relation between the two, you can start
 //!
 //! [polkadot]: https://img.shields.io/badge/polkadot-E6007A?style=for-the-badge&logo=polkadot&logoColor=white
 //! [github]: https://img.shields.io/badge/github-8da0cb?style=for-the-badge&labelColor=555555&logo=github
-
 ```
 
 ### Dispatchable

From 121e2515116fee599c09d864edeb6ef49ebbe2c7 Mon Sep 17 00:00:00 2001
From: Kian Paimani <5588131+kianenigma@users.noreply.github.com>
Date: Tue, 23 May 2023 10:49:06 +0200
Subject: [PATCH 17/18] Update docs/DOCUMENTATION_GUIDELINES.md

Co-authored-by: Sebastian Kunert <skunert49@gmail.com>
---
 docs/DOCUMENTATION_GUIDELINES.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/DOCUMENTATION_GUIDELINES.md b/docs/DOCUMENTATION_GUIDELINES.md
index ff3d497df4bdc..0e660834cd608 100644
--- a/docs/DOCUMENTATION_GUIDELINES.md
+++ b/docs/DOCUMENTATION_GUIDELINES.md
@@ -1,4 +1,4 @@
-wra# Substrate Documentation Guidelines
+# 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`.
 

From a34d7ae900d472d2151e2df27965d991685b1196 Mon Sep 17 00:00:00 2001
From: kianenigma <kian@parity.io>
Date: Fri, 26 May 2023 10:01:42 +0200
Subject: [PATCH 18/18] storage

---
 docs/DOCUMENTATION_GUIDELINES.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/DOCUMENTATION_GUIDELINES.md b/docs/DOCUMENTATION_GUIDELINES.md
index ff3d497df4bdc..ef6dd972534f4 100644
--- a/docs/DOCUMENTATION_GUIDELINES.md
+++ b/docs/DOCUMENTATION_GUIDELINES.md
@@ -250,5 +250,5 @@ pub fn name_of_dispatchable(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.
+2. Consider explaining the crypto-economics of how a deposit is being taken in return of the storage being used.
+3. Consider explaining why it is safe for the storage item to be unbounded, if `#[pallet::unbounded]` or `#[pallet::without_storage_info]` is being used.