PRDoc new schema (#1946)

## Overview

This PR brings in the new version of prdoc v0.0.6 and allows:
- local schema
- local config
- local template

It also fixes the existing prdoc files to match the new schema.

## todo

- [x] add a brief doc/tldr to help contributors get started
- [x] test CI
- [x] finalize schema
- [x] publish the next `prdoc` cli version (v0.0.7 or above)

---------

Co-authored-by: Egor_P <egor@parity.io>
Co-authored-by: Bastian Köcher <git@kchr.de>

docs/CONTRIBUTING.md

@@ -93,22 +93,12 @@ The reviewers are also responsible to check:
 
 All Pull Requests must contain proper title & description.
 
-Some Pull Requests can be exempt of `prdoc` documentation, those
-must be labelled with
+Some Pull Requests can be exempt of `prdoc` documentation, those must be labelled with
 [`R0-silent`](https://github.com/paritytech/labels/blob/main/ruled_labels/specs_polkadot-sdk.yaml#L89-L91).
 
 Non "silent" PRs must come with documentation in the form of a `.prdoc` file.
-A `.prdoc` documentation is made of a text file (YAML) named `/prdoc/pr_NNNN.prdoc` where `NNNN` is the PR number.
-For convenience, those file can also contain a short description/title: `/prdoc/pr_NNNN_pr-foobar.prdoc`.
 
-The CI automation checks for the presence and validity of a `prdoc` in the `/prdoc` folder.
-Those files need to comply with a specific [schema](https://github.com/paritytech/prdoc/blob/master/schema_user.json). It
-is highly recommended to [make your editor aware](https://github.com/paritytech/prdoc#schemas) of the schema as it is
-self-described and will assist you in writing correct content.
-
-This schema is also embedded in the
-[prdoc](https://github.com/paritytech/prdoc) utility that can also be used to generate and check the validity of a
-`prdoc` locally.
+See more about `prdoc` [here](./prdoc.md)
 
 ## Helping out
 

docs/DOCUMENTATION_GUIDELINES.md

@@ -225,7 +225,7 @@ For the top-level pallet docs, consider the following template:
 //!
 //! ## 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 
+//! <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 line below as-is:>
 //!
 //! See the [`pallet`] module for more information about the interfaces this pallet exposes, including its
@@ -349,3 +349,7 @@ Consider the fact that, similar to dispatchables, these docs will be part of the
 and might be used by wallets and explorers.
 
 Specifically for `error`, explain why the error has happened, and what can be done in order to avoid it.
+
+## Documenting Changes/PR
+
+See [PRDoc](./prdoc.md).

docs/prdoc.md

@@ -0,0 +1,71 @@
+# PRDoc
+
+## Intro
+
+With the merge of [PR #1946](https://github.com/paritytech/polkadot-sdk/pull/1946), a new method for
+documenting changes has been introduced: `prdoc`. The [prdoc repository](https://github.com/paritytech/prdoc)
+contains more documentation and tooling.
+
+The current document describes how to quickly get started authoring `PRDoc` files.
+
+## Requirements
+
+When creating a PR, the author needs to decides with the `R0` label whether the change (PR) should
+appear in the release notes or not.
+
+Labelling a PR with `R0` means that no `PRDoc` is required.
+
+A PR without the `R0` label **does** require a valid `PRDoc` file to be introduced in the PR.
+
+## PRDoc how-to
+
+A `.prdoc` file is a YAML file with a defined structure (ie JSON Schema).
+
+For significant changes, a `.prdoc` file is mandatory and the file must meet the following
+requirements:
+- file named `pr_NNNN.prdoc` where `NNNN` is the PR number.
+  For convenience, those file can also contain a short description: `pr_NNNN_foobar.prdoc`.
+- located under the [`prdoc` folder](https://github.com/paritytech/polkadot-sdk/tree/master/prdoc) of the repository
+- compliant with the [JSON schema](https://json-schema.org/) defined in `prdoc/schema_user.json`
+
+Those requirements can be fulfilled manually without any tooling but a text editor.
+
+## Tooling
+
+Users might find the following helpers convenient:
+- Setup VSCode to be aware of the prdoc schema: see [using VSCode](https://github.com/paritytech/prdoc#using-vscode)
+- Using the `prdoc` cli to:
+  - generate a `PRDoc` file from a [template defined in the Polkadot SDK
+    repo](https://github.com/paritytech/polkadot-sdk/blob/master/prdoc/.template.prdoc) simply providing a PR number
+  - check the validity of one or more `PRDoc` files
+
+## `prdoc` cli usage
+
+The `prdoc` cli documentation can be found at https://github.com/paritytech/prdoc#prdoc
+
+tldr:
+- `prdoc generate <NNNN>`
+- `prdoc check -n <NNNN>`
+
+where <NNNN> is the PR number.
+
+## Pick an audience
+
+While describing a PR, the author needs to consider which audience(s) need to be addressed.
+The list of valid audiences is described and documented in the JSON schema as follow:
+
+- `Node Dev`: Those who build around the client side code. Alternative client builders, SMOLDOT, those who consume RPCs.
+   These are people who are oblivious to the runtime changes. They only care about the meta-protocol, not the protocol
+   itself.
+
+- `Runtime Dev`: All of those who rely on the runtime. A parachain team that is using a pallet. A DApp that is using a
+   pallet. These are people who care about the protocol (WASM), not the meta-protocol (client).
+
+- `Node Operator`: Those who don't write any code and only run code.
+
+- `Runtime User`: Anyone using the runtime. This can be a token holder or a dev writing a front end for a chain.
+
+## Tips
+
+The PRDoc schema is defined in each repo and usually is quite restrictive.
+You cannot simply add a new property to a `PRDoc` file unless the Schema allows it.