diff --git a/distance-oracle/README.md b/distance-oracle/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..5a4233827626c53a79da4b6750ec3bb93f6918c3
--- /dev/null
+++ b/distance-oracle/README.md
@@ -0,0 +1,20 @@
+# Distance oracle
+
+> for explanation about the Duniter web of trust, see https://duniter.org/wiki/web-of-trust/deep-dive-wot/
+
+Distance computation on the Duniter web of trust is an expensive operation that should not be included in the runtime for multiple reasons:
+
+- it could exceed the time available for a block computation
+- it takes a lot of resource from the host machine
+- the result is not critical to the operation of Ğ1
+
+It is then separated into an other program that the user (a duniter smith) can choose to run or not. This program publishes its result in a inherent and the network selects the median of the results given by the smith who published some.
+
+## Structure
+
+This feature is organized in multiple parts:
+
+- **/distance-oracle/** (here): binary executing the distance algorithm
+- **/primitives/distance/**: primitive types used both by client and runtime
+- **/client/distance/**: exposes the `create_distance_inherent_data_provider` which provides data to the runtime
+- **/pallets/distance/**: distance pallet exposing type, traits, storage/calls/hooks executing in the runtime
\ No newline at end of file
diff --git a/pallets/README.md b/pallets/README.md
index cf67622f8be75f2895f450418ee77d468db3810d..4e229119e7a0cb4fb333f433b3eb374d1ae87b32 100644
--- a/pallets/README.md
+++ b/pallets/README.md
@@ -10,7 +10,7 @@ These pallets are at the core of Duniter/Ğ1 currency
 - **`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.
+- **`distance`** Publishes median of distance computation results provided by inherents coming from `distance-oracle` workers.
 - **`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.
diff --git a/pallets/distance/README.md b/pallets/distance/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..7b34661e1a6bb99892808d29d5aa24b82a7fb4fe
--- /dev/null
+++ b/pallets/distance/README.md
@@ -0,0 +1,47 @@
+# Distance pallet
+
+The distance pallet uses results provided in a file by the `distance-oracle` offchain worker.
+At some point an inherent is called to submit the results of this file to the blockchain.
+The pallet then selects the median of the results (reach perbill) of an evaluation pool and fills the storage with the result status.
+The status of an identity can be:
+
+- inexistant: distance evaluation has not been requested or has expired
+- pending: distance evaluation for this identity has been requested and is waiting two sessions for results
+- valid: distance has been evaluated positively for this identity
+
+The result of the evaluation is used by `duniter-wot` pallet to determine if an identity can get / should loose membership to the web of trust. 
+
+## Process
+
+Any account can request a distance evaluation for a given identity provided it has enough currency to be reserved. In this case, the distance status is marked as pending and in the next session, inherents can start to publish results. 
+
+This is how a result is published:
+
+1. local worker creates a file containing the result of computation
+1. inherent is created with the data from this file
+1. author is registered as an evaluator
+1. the result is added to the current evaluation pool
+1. a flag is set to prevent other distance evaluation in the same block
+
+On each new session:
+
+1. old results set to expire at this session do expire
+1. results from the current pool (previous session's result pool) are taken and for each identity
+    - the median of the distance results for this identity is chosen
+    - if the distance is ok, the distance is marked as valid
+    - if the distance is ko, the result for this identity is removed and reserved currency is slashed (from the account which requested the evaluation)
+
+Then, in other pallets, when a membership is claimed, it is possible to look if there is a valid evaluation of distance for this identity.
+
+## Pools
+
+Evaluation pools are made of two components:
+
+- a set of evaluators
+- a vec of results
+
+The evaluation are separated in three pools (N - 2 is the session index):
+
+- pool number N - 1 % 3: results from the previous session used in the current one (let empty for next session)
+- pool number N + 0 % 3: inherent results are added there
+- pool number N + 1 % 3: identities are added there for evaluation
\ No newline at end of file