diff --git a/pallets/README.md b/pallets/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..1f0305b5d6fc4a8d3066dc0643a3288433b74bd9
--- /dev/null
+++ b/pallets/README.md
@@ -0,0 +1,23 @@
+# Duniter pallets
+
+Duniter uses some [parity pallets](https://github.com/duniter/substrate/tree/master/frame) available in our substrate fork, and some defined here. Each pallet has its own readme, but here is a summary:
+
+## Business processes pallets
+
+These pallets are at the core of Duniter/Äž1 currency
+
+- **`authority-members`** Duniter authorities are not selected with staking but through a smith web of trust.
+- **`certification`** Certifications are the "edges" of Duniter's dynamic directed graph. They mean the acceptation of a Licence.
+- **`duniter-account`** Duniter customized the `AccountData` defined in the `Balances` pallet to introduce a `RandomId`.
+- **`duniter-wot`** Merges identities, membership, certifications and distance pallets to implement Duniter Web of Trust.
+- **`duniter-distance`** Offchain worker used to compute distance criterion.
+- **`identity`** Identities are the "nodes" of Duniter's dynamic directed graph. They are one-to-one mapping to human being.
+- **`membership`** Membership defines the state of identities. They can be member or not of the different WoTs.
+- **`universal-dividend`** UD is at the basis of Äž1 "libre currency". It is both a kind of "basic income" and a measure unit.
+
+## Functional pallets
+
+- **`duniter-test-parameters`** Test parameters only used in ÄžDev to allow tweaking parameters more easily.
+- **`oneshot-account`** Oneshot accounts are light accounts only used once for anonimity or convenience use case.
+- **`provide-randomness`** Lets blockchain users ask for a verifiable random number.
+- **`upgrade-origin`** Allows some origins to dispatch a call as root.
\ No newline at end of file
diff --git a/pallets/authority-members/README.md b/pallets/authority-members/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..c99560fb5fca577896fc76824947772a91e47f23
--- /dev/null
+++ b/pallets/authority-members/README.md
@@ -0,0 +1,21 @@
+# Duniter authority members pallet
+
+In a permissioned network, we have to define the set of authorities, and among these authorities, the ones taking part in the next session. That's what authority members pallet does. In practice:
+
+- it manages a `Members` set with some custom rules
+- it implements the `SessionManager` trait from the session frame pallet
+
+## Entering the set of authorities
+
+To become part of Duniter authorities, one has to complete these steps:
+
+1. become member of the main web of trust
+1. request membership to the smith sub wot
+1. get enough certs to get smith membership
+1. claim membership to the set of authorities
+
+Then one can "go online" and "go offline" to enter or leave two sessions after.
+
+## Staying in the set of authorities
+
+If a smith is offline more than `MaxOfflineSessions`, he leaves the set of authorities.
\ No newline at end of file
diff --git a/pallets/authority-members/src/lib.rs b/pallets/authority-members/src/lib.rs
index 9a1d9f4d3f20c223fd08b08eaf3d34c96966ae56..3767ba1dde7857c1fcad215fbc6d66a50c8acc8e 100644
--- a/pallets/authority-members/src/lib.rs
+++ b/pallets/authority-members/src/lib.rs
@@ -521,6 +521,7 @@ impl<T: Config> pallet_session::SessionManager<T::ValidatorId> for Pallet<T> {
 
         if members_ids_to_add.is_empty() {
             if members_ids_to_del.is_empty() {
+                // when no change to the set of autorities, return None
                 return None;
             } else {
                 for member_id in &members_ids_to_del {
@@ -540,6 +541,7 @@ impl<T: Config> pallet_session::SessionManager<T::ValidatorId> for Pallet<T> {
             Self::deposit_event(Event::IncomingAuthorities(members_ids_to_add.clone()));
         }
 
+        // updates the list of OnlineAuthorities and returns the list of their key
         Some(
             OnlineAuthorities::<T>::mutate(|members_ids| {
                 for member_id in members_ids_to_del {
diff --git a/pallets/certification/README.md b/pallets/certification/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..a84e9f9eadc0250a756b32d0bfb1cf3e24c198bb
--- /dev/null
+++ b/pallets/certification/README.md
@@ -0,0 +1,8 @@
+# Duniter certification pallet
+
+Duniter certifications are the *edges* in the Duniter [Web of Trust](../duniter-wot/). They can have different meanings:
+
+- in the case of the main WoT, they mean "I have met this person IRL and trust them" (see Äž1 Licence)
+- in the case of the smith sub-WoT, they mean "I trust this person to be able to run Duniter securely" (see smith Licence)
+
+This pallet manages certifications creation, deletion...
\ No newline at end of file
diff --git a/pallets/duniter-account/README.md b/pallets/duniter-account/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..d9b809d8af43bfdd3598696936445d0b38b5dc71
--- /dev/null
+++ b/pallets/duniter-account/README.md
@@ -0,0 +1,17 @@
+# Duniter account pallet
+
+Duniter customizes the `AccountData` of the `Balances` Substrate pallet. In particular, it adds a field `RandomId`.
+
+## RandomID
+
+The RandomId field was added with the idea to provide a unique id that can not be controlled by user to serve as a basis for robust identification. The discussion is available on the forum.
+
+https://forum.duniter.org/t/la-solution-pour-des-identicones-securisees-le-random-id/9126
+
+## Account creation fee
+
+DuniterAccount defines a creation fee that is preleved to the account one block after its creation. This fee goes to the treasury.
+
+## Sufficient 
+
+DuniterAccount tweaks the substrate AccountInfo to allow identity accounts to exist without existential deposit. This allows to spare the creation fee.
\ No newline at end of file
diff --git a/pallets/duniter-account/src/types.rs b/pallets/duniter-account/src/types.rs
index cf833bdab1f40a1b1ea1040e29c00013d356078d..91a23e30877d81afe2f2bd06ca8cffeeefac7592 100644
--- a/pallets/duniter-account/src/types.rs
+++ b/pallets/duniter-account/src/types.rs
@@ -20,11 +20,17 @@ use scale_info::TypeInfo;
 use sp_core::H256;
 use sp_runtime::traits::Zero;
 
+// see `struct AccountData` for details in substrate code
 #[derive(Clone, Decode, Default, Encode, Eq, MaxEncodedLen, PartialEq, RuntimeDebug, TypeInfo)]
 pub struct AccountData<Balance> {
+    /// A random identifier that can not be chosen by the user
+    // this intends to be used as a robust identification system
     pub(super) random_id: Option<H256>,
+    // see Substrate AccountData
     pub(super) free: Balance,
+    // see Substrate AccountData
     pub(super) reserved: Balance,
+    // see Substrate AccountData
     fee_frozen: Balance,
 }
 
diff --git a/pallets/duniter-test-parameters/README.md b/pallets/duniter-test-parameters/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..80a352ff46980635c72de80029cedc324ea6da30
--- /dev/null
+++ b/pallets/duniter-test-parameters/README.md
@@ -0,0 +1,3 @@
+# Duniter test parameters
+
+This pallet allows ÄžDev runtime to tweak parameter values instead of having it runtime constants.
\ No newline at end of file
diff --git a/pallets/duniter-wot/README.md b/pallets/duniter-wot/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..4ac1baf7bc13165d1eb323ea5ef82018492e08a3
--- /dev/null
+++ b/pallets/duniter-wot/README.md
@@ -0,0 +1,21 @@
+# Duniter Web of Trust pallet
+
+Duniter WoT is at the core of its identity system and is a big improvement compared to PGP WoT. It is a dynamic directed graph whose nodes are [identities](../identity/) and edges [certifications](../certification/).
+
+There are two instances:
+
+- the main WoT, for every human
+- the smith sub-WoT, for authorities
+
+It has both static and dynamic rules, controlling the condition to join and remain [member](../membership/).
+
+- static rules
+    - minimum number of received certifications (min indegree)
+    - maximum number of emited certifications (max outdegree)
+    - distance criterion (see distance pallet)
+- dynamic rules
+    - time interval between two certifications
+    - certification duration (see certification pallet)
+    - membership renewal (see membership pallet)
+
+This pallet's main role is to check the Web of Trust rules.
\ No newline at end of file
diff --git a/pallets/duniter-wot/src/lib.rs b/pallets/duniter-wot/src/lib.rs
index e16695040c4d17761e7bd1698d9cbdc40eb37868..9c717b731d7915ec91e32b4c1885389a4fad54bd 100644
--- a/pallets/duniter-wot/src/lib.rs
+++ b/pallets/duniter-wot/src/lib.rs
@@ -271,9 +271,9 @@ where
                 }
             }
             // Membership revocation cases:
-            // - Triggered by identity removal: the identity underlying will by removed by the
+            // - Triggered by main identity removal: the underlying identity will be removed by the
             // caller.
-            // - Triggered by the membership pallet: it's ondly possible for the sub-wot, so we
+            // - Triggered by the membership pallet: it's only possible for a sub-wot, so we
             // should not remove the underlying identity
             // So, in any case, we must do nothing
             sp_membership::Event::<IdtyIndex, MetaData>::MembershipRevoked(_) => {}
diff --git a/pallets/identity/README.md b/pallets/identity/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..1d728ed92a602053153a15a3f45e62971fb74eea
--- /dev/null
+++ b/pallets/identity/README.md
@@ -0,0 +1,43 @@
+# Duniter identity pallet
+
+Duniter has a builtin identity system that does not work with external registrar compared to [parity identity pallet](https://github.com/paritytech/substrate/tree/master/frame/identity).
+
+## Duniter identity
+
+A Duniter identity contains:
+
+- its **owner key** (that can change)
+- an optional **old owner key** with the date of the key change
+- a **status** that can be
+  - created (by an existing identity)
+  - confirmed (by owner, comes with a name)
+  - validated (that has become member in the allowed timeframe)
+
+It also contains:
+
+- the block number at which it can emit its **next certification**
+- the block number at which it can be **removed from storage**
+
+It also contains attached data defined by the runtime that can be for example
+
+- the number of the first UD it is eligible to
+
+### Name
+
+Each identity is declared with a name emited on confirmation event. Duniter keeps a list of identity names hash to ensure unicity. 
+
+### Owner key
+
+The idea of the owner key is to allow the user to keep a fixed identity while changing the keys for security reasons. For example when a device with the keys might have been compromised. There is a limit to the frequency of owner key change and the old owner key can still revoke the identity for a given period.
+
+### Status / removable date
+
+The status is a temporary value allowing to prune identities before they become member. When an identity is not valiated (not member of the WoT for instance), it can be removed when the date is reached. The remove date of a validated identity is block zero.
+
+### Next certification
+
+The next certification is a rate limit to the emission of certification (and then identity creation).
+
+### Revokation
+
+Revoking an identity basically means deleting it.
\ No newline at end of file
diff --git a/pallets/membership/README.md b/pallets/membership/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..ff9c1f0c69c70bcfe38f02089d35027824680f98
--- /dev/null
+++ b/pallets/membership/README.md
@@ -0,0 +1,3 @@
+# Duniter membership pallet
+
+Duniter membership is related to duniter Web of Trust and more specific than [parity membership pallet](https://github.com/paritytech/substrate/tree/master/frame/membership). It is used only internally by the identity, WoT, and distance pallets. In particular, it is adding the concept of "pending membership" which is an intermediate state where the identity is waiting to become member.
\ No newline at end of file
diff --git a/pallets/oneshot-account/README.md b/pallets/oneshot-account/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..7d3f030eabb1384ae07203d6577dae0bde54b5fa
--- /dev/null
+++ b/pallets/oneshot-account/README.md
@@ -0,0 +1,3 @@
+# Duniter oneshot account pallet
+
+Duniter provides light accounts without `AccountInfo` (nonce, consumers, providers, sufficients, free, reserved, misc_frozen, fee_frozen) that can only be consumed once. This should reduce transaction weight and then fees. The use case is anonymous accounts or physical supports.
\ No newline at end of file
diff --git a/pallets/provide-randomness/README.md b/pallets/provide-randomness/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..12138fbd60ba21715edbbb1cd42ad7c477d8bbf4
--- /dev/null
+++ b/pallets/provide-randomness/README.md
@@ -0,0 +1,3 @@
+# Duniter provide randomness pallet
+
+TODO
\ No newline at end of file
diff --git a/pallets/universal-dividend/README.md b/pallets/universal-dividend/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..b7e862551d60c73dd215e25d31647c2357dfc4e0
--- /dev/null
+++ b/pallets/universal-dividend/README.md
@@ -0,0 +1,5 @@
+# Duniter universal dividend pallet
+
+One of the main features of Duniter is the Universal Dividend based on the Relative Theory of Money. It is both a daily monetary creation and a measure unit.
+
+This pallet provides functions to create UDs and transfer an amount of currency counted in UD. It should be noted that the UD is not actually created every day on every account which would be very resource consuming but must be claimed by the member in a given extrinsic.
\ No newline at end of file
diff --git a/pallets/upgrade-origin/README.md b/pallets/upgrade-origin/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..204c2a034feefc807118bd55572fc21b5c5be25c
--- /dev/null
+++ b/pallets/upgrade-origin/README.md
@@ -0,0 +1,3 @@
+# Duniter upgrade origin pallet
+
+TODO
\ No newline at end of file
diff --git a/primitives/README.md b/primitives/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..acbca4dcb851b26e45213d6292317641d6e97ef3
--- /dev/null
+++ b/primitives/README.md
@@ -0,0 +1,3 @@
+# Primitives
+
+TODO
\ No newline at end of file
diff --git a/resources/README.md b/resources/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..5bd6a187fa142bcd8c0372c3a39a2ad1795c4a22
--- /dev/null
+++ b/resources/README.md
@@ -0,0 +1,3 @@
+# Resources
+
+Files used for different purpose like tests.
\ No newline at end of file
diff --git a/runtime/README.md b/runtime/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..4f74e8beafea64b015299da196c4d23e0941dc20
--- /dev/null
+++ b/runtime/README.md
@@ -0,0 +1,8 @@
+# Runtimes
+
+Duniter client can run several runtimes.
+
+- ÄžDev is for development purpose
+- ĞTest is to prepare Ğ1 migration and test features before deploying on Ǧ1
+- Äž1 is the production currency
+
diff --git a/scripts/README.md b/scripts/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..95a516bbdfe62ad34c6d6cf22f743e79e8feffb3
--- /dev/null
+++ b/scripts/README.md
@@ -0,0 +1,3 @@
+# Scripts
+
+Scripts not moved to xtasks because they only depend on Docker and not Rust.
\ No newline at end of file
diff --git a/xtask/README.md b/xtask/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..3f856c57016a1badafd368db3324cdd8945f3edc
--- /dev/null
+++ b/xtask/README.md
@@ -0,0 +1,9 @@
+# Xtask
+
+We choose [`xtask`](https://github.com/matklad/cargo-xtask/) to run Rust scripts using `cargo`. To build these scripts, just run:
+
+```bash
+cargo xtask # this will build the scripts and show the available commands
+```
+
+These scripts mainly deal with runtime operations.
\ No newline at end of file