diff --git a/pallets/authority-members/README.md b/pallets/authority-members/README.md
index af43b78ab2efa7c154a25e40bbd0fffb7c174cda..c99560fb5fca577896fc76824947772a91e47f23 100644
--- a/pallets/authority-members/README.md
+++ b/pallets/authority-members/README.md
@@ -1,3 +1,21 @@
 # Duniter authority members pallet
 
-Duniter authorities are not selected with staking but thanks the the "smith" web of trust. A member of the smith WoT can join or leave the set of authorities whenever he or she wants.
+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 {