diff --git a/substrate/frame/identity/README.md b/substrate/frame/identity/README.md
index 0203656eff46..701a3cceb30d 100644
--- a/substrate/frame/identity/README.md
+++ b/substrate/frame/identity/README.md
@@ -1,9 +1,11 @@
-# Identity Module
+# pallet-identity
 
-- [`identity::Config`](https://docs.rs/pallet-identity/latest/pallet_identity/trait.Config.html)
-- [`Call`](https://docs.rs/pallet-identity/latest/pallet_identity/enum.Call.html)
+## Identity Pallet
 
-## Overview
+- [`Config`]
+- [`Call`]
+
+### Overview
 
 A federated naming system, allowing for multiple registrars to be added from a specified origin.
 Registrars can set a fee to provide identity-verification service. Anyone can put forth a
@@ -23,32 +25,53 @@ by definition, these have equivalent ownership and each has an individual name.
 The number of registrars should be limited, and the deposit made sufficiently large, to ensure
 no state-bloat attack is viable.
 
-## Interface
+#### Usernames
+
+The pallet provides functionality for username authorities to issue usernames. When an account
+receives a username, they get a default instance of `IdentityInfo`. Usernames also serve as a
+reverse lookup from username to account.
+
+Username authorities are given an allocation by governance to prevent state bloat. Usernames
+impose no cost or deposit on the user.
+
+Users can have multiple usernames that map to the same `AccountId`, however one `AccountId` can
+only map to a single username, known as the _primary_.
+
+### Interface
 
-### Dispatchable Functions
+#### Dispatchable Functions
 
-#### For general users
-- `set_identity` - Set the associated identity of an account; a small deposit is reserved if not
+##### For General Users
+* `set_identity` - Set the associated identity of an account; a small deposit is reserved if not
   already taken.
-- `clear_identity` - Remove an account's associated identity; the deposit is returned.
-- `request_judgement` - Request a judgement from a registrar, paying a fee.
-- `cancel_request` - Cancel the previous request for a judgement.
-
-#### For general users with sub-identities
-- `set_subs` - Set the sub-accounts of an identity.
-- `add_sub` - Add a sub-identity to an identity.
-- `remove_sub` - Remove a sub-identity of an identity.
-- `rename_sub` - Rename a sub-identity of an identity.
-- `quit_sub` - Remove a sub-identity of an identity (called by the sub-identity).
-
-#### For registrars
-- `set_fee` - Set the fee required to be paid for a judgement to be given by the registrar.
-- `set_fields` - Set the fields that a registrar cares about in their judgements.
-- `provide_judgement` - Provide a judgement to an identity.
-
-#### For super-users
-- `add_registrar` - Add a new registrar to the system.
-- `kill_identity` - Forcibly remove the associated identity; the deposit is lost.
+* `clear_identity` - Remove an account's associated identity; the deposit is returned.
+* `request_judgement` - Request a judgement from a registrar, paying a fee.
+* `cancel_request` - Cancel the previous request for a judgement.
+* `accept_username` - Accept a username issued by a username authority.
+* `remove_expired_approval` - Remove a username that was issued but never accepted.
+* `set_primary_username` - Set a given username as an account's primary.
+* `remove_dangling_username` - Remove a username that maps to an account without an identity.
+
+##### For General Users with Sub-Identities
+* `set_subs` - Set the sub-accounts of an identity.
+* `add_sub` - Add a sub-identity to an identity.
+* `remove_sub` - Remove a sub-identity of an identity.
+* `rename_sub` - Rename a sub-identity of an identity.
+* `quit_sub` - Remove a sub-identity of an identity (called by the sub-identity).
+
+##### For Registrars
+* `set_fee` - Set the fee required to be paid for a judgement to be given by the registrar.
+* `set_fields` - Set the fields that a registrar cares about in their judgements.
+* `provide_judgement` - Provide a judgement to an identity.
+
+##### For Username Authorities
+* `set_username_for` - Set a username for a given account. The account must approve it.
+
+##### For Superusers
+* `add_registrar` - Add a new registrar to the system.
+* `kill_identity` - Forcibly remove the associated identity; the deposit is lost.
+* `add_username_authority` - Add an account with the ability to issue usernames.
+* `remove_username_authority` - Remove an account with the ability to issue usernames.
 
 [`Call`]: ./enum.Call.html
 [`Config`]: ./trait.Config.html