diff --git a/pallets/membership/README.md b/pallets/membership/README.md
index ff9c1f0c69c70bcfe38f02089d35027824680f98..116b2addd9d736c6452d4dc3dcbe83f1959c62de 100644
--- a/pallets/membership/README.md
+++ b/pallets/membership/README.md
@@ -1,3 +1,25 @@
 # 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
+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.
+
+## Main Web of Trust
+
+When used in conjunction with the main Web of Trust, the membership pallet is combined with the Duniter-WoT pallet and the identity pallet, resulting in the following functionality:
+
+- `request_membership` is automatically invoked when confirming identity and should not be called manually. It will add the identity to the pending membership.
+- `claim_membership` is automatically triggered during identity validation and should not be manually invoked. This process requires a pending membership, sufficient membership certificates, and a valid distance. Membership is granted upon successful completion of these requirements.
+- `renew_membership` requires a valid membership and a valid distance status to extend the validity period of a membership.
+- `revoke_membership` is automatically executed when a membership expires and should not be called manually.
+
+In practice, a new user creates an account, confirms identity using the `confirm_identity` call from the identity pallet, and is added to the pending membership. The user then validates it identity using the `validate_identity` call from the identity pallet, triggering a membership claim. If the certification and distance requirements are met, the identity is granted membership.
+
+## Sub Web of Trust Smith
+
+Functionality related to the Smith Web of Trust involves the following:
+
+- `request_membership` requires a validated identity for the member to be added to the pending membership.
+- `claim_membership` requires a pending membership, sufficient smith certificates, and a valid distance status for the identity to be included among the authority members.
+- `renew_membership` needs a valid membership and a valid distance status to extend the membership's validity period.
+- `revoke_membership` requires a valid origin to revoke the membership.
+
+In practice, a user must complete all steps to gain membership in the main Web Of Trust. They can then manually request smith membership using the `request_membership` call of the membership pallet. The membership can be claimed using the `claim_membership` call from the membership pallet, and if the identity meets smith certificate and distance requirements, it will be added to the authority members.
\ No newline at end of file
diff --git a/pallets/membership/src/lib.rs b/pallets/membership/src/lib.rs
index 60c346a2f0fcdeebcf24696106637cae2ce3100d..1fcd8ce749ece64b878bb6dba96219b37676ab0f 100644
--- a/pallets/membership/src/lib.rs
+++ b/pallets/membership/src/lib.rs
@@ -176,7 +176,7 @@ pub mod pallet {
             member: T::IdtyId,
             expire_on: BlockNumberFor<T>,
         },
-        /// A pending membership request has expired.
+        /// A pending membership has expired.
         PendingMembershipExpired { member: T::IdtyId },
     }
 
diff --git a/primitives/membership/src/lib.rs b/primitives/membership/src/lib.rs
index 4fb1629f63128d311ae7a1ca5293f9ad620f97ff..e362219e4fbd1465c8aa0aa7eaac6400cb0387fb 100644
--- a/primitives/membership/src/lib.rs
+++ b/primitives/membership/src/lib.rs
@@ -28,15 +28,15 @@ use scale_info::TypeInfo;
 use serde::{Deserialize, Serialize};
 
 pub enum Event<IdtyId> {
-    /// A membership has acquired
+    /// A membership was acquired.
     MembershipAcquired(IdtyId),
     /// A membership was terminated.
     MembershipTerminated(IdtyId),
-    /// A membership has renewed
+    /// A membership was renewed.
     MembershipRenewed(IdtyId),
-    /// An identity requested membership
+    /// A pending membership request was added.
     PendingMembershipAdded(IdtyId),
-    /// A pending membership request has expired
+    /// A pending membership request has expired.
     PendingMembershipExpired(IdtyId),
 }