diff --git a/src/main/asciidoc/_chapters/datamodel.adoc b/src/main/asciidoc/_chapters/datamodel.adoc
index c8164e4696a8..2e6070dbc90b 100644
--- a/src/main/asciidoc/_chapters/datamodel.adoc
+++ b/src/main/asciidoc/_chapters/datamodel.adoc
@@ -238,6 +238,23 @@ create 'bar', 'fam'
 ----
 ====
 
+[[namespace_table]]
+=== About hbase:namespace table
+We used to have a system table called `hbase:namespace` for storing the namespace information.
+
+It introduced some painful bugs in the past, especially that it may hang the master startup thus
+hang the whole cluster. This is because meta table also has a namespace, so it depends on namespace
+table. But namespace table also depends on meta table as meta table stores the location of all
+regions. This is a cyclic dependency so sometimes namespace and meta table will wait for each other
+to online and hang the master start up.
+
+It is not easy to fix so in 3.0.0, we decided to completely remove the `hbase:namespace` table and
+fold its content into the `ns` family in `hbase:meta` table. When upgrading from 2.x to 3.x, the
+migration will be done automatically and the `hbase:namespace` table will be disabled after the
+migration is done. You are free to leave it there for sometime and finally drop it.
+
+For more tails, please see https://issues.apache.org/jira/browse/HBASE-21154[HBASE-21154].
+
 == Table
 
 Tables are declared up front at schema definition time.
diff --git a/src/main/asciidoc/_chapters/upgrading.adoc b/src/main/asciidoc/_chapters/upgrading.adoc
index 83030cc5038a..055acd968078 100644
--- a/src/main/asciidoc/_chapters/upgrading.adoc
+++ b/src/main/asciidoc/_chapters/upgrading.adoc
@@ -327,6 +327,9 @@ Quitting...
 The RegionServer Grouping feature has been reimplemented. See section
 <<migrating.rsgroup>> in <<ops_mgt>> for more details.
 
+The `hbase:namespace` table has been removed and fold into `hbase:meta`. See section
+<<namespace_table>> in <<datamodel>> for more details.
+
 [[upgrade2.4]]
 There is no special consideration upgrading to hbase-2.4.x from 2.3.x. And for earlier versions,
 just follow the <<upgrade2.3>> guide. In general, 2.2.x should be rolling upgradeable, for 2.1.x