diff --git a/vesting/README.md b/vesting/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..6f44ec2e3e7680aaac94143b77eada93e166ab71
--- /dev/null
+++ b/vesting/README.md
@@ -0,0 +1,9 @@
+# Vesting Module
+
+## Overview
+
+Vesting module provides a means of scheduled balance lock on an account. It uses the *graded vesting* way, which unlocks a specific amount of balance every period of time, until all balance unlocked.
+
+### Vesting Schedule
+
+The schedule of a vesting is described by data structure `VestingSchedule`: from the block number of `start`, for every `period` amount of blocks, `per_period` amount of balance would unlocked, until number of periods `period_count` reached. Note in vesting schedules, *time* is measured by block number. All `VestingSchedule`s under an account could be queried in chain state.
diff --git a/vesting/src/lib.rs b/vesting/src/lib.rs
index c080592a8a3c2faf014e8485f4325a532e351c3a..38aad903d134c44e299fcee810e778e6b24d350a 100644
--- a/vesting/src/lib.rs
+++ b/vesting/src/lib.rs
@@ -1,3 +1,25 @@
+//! # Vesting Module
+//!
+//! ## Overview
+//!
+//! Vesting module provides a means of scheduled balance lock on an account. It uses the *graded vesting* way, which
+//! unlocks a specific amount of balance every period of time, until all balance unlocked.
+//!
+//! ### Vesting Schedule
+//!
+//! The schedule of a vesting is described by data structure `VestingSchedule`: from the block number of `start`, for
+//! every `period` amount of blocks, `per_period` amount of balance would unlocked, until number of periods
+//! `period_count` reached. Note in vesting schedules, *time* is measured by block number. All `VestingSchedule`s under
+//! an account could be queried in chain state.
+//!
+//! ## Interface
+//!
+//! ### Dispatchable Functions
+//!
+//! - `add_vesting_schedule` - Add a new vesting schedule for an account.
+//! - `claim` - Claim unlocked balances.
+//! - `update_vesting_schedules` - Update all vesting schedules under an account, `root` origin required.
+
 #![cfg_attr(not(feature = "std"), no_std)]
 
 use codec::{Decode, Encode, HasCompact};