diff --git a/1-introduction.md b/1-introduction.md
index 2db013aaf..9bd70b8e7 100644
--- a/1-introduction.md
+++ b/1-introduction.md
@@ -5,6 +5,9 @@ While developing [IPFS, the InterPlanetary FileSystem](https://ipfs.io/), we cam
 
 In order to build this library, we focused on tackling problems independently, creating less complex solutions with powerful abstractions that, when composed, can offer an environment for a peer-to-peer application to work successfully.
 
+| ⚠️ Warning: parts of this document are incomplete and out of date. Please see [this issue](https://github.com/libp2p/specs/issues/156), and look for deprecation notices throughout. ⚠️ |
+| --- |
+
 ## 1.1 Motivation
 
 `libp2p` is the result of our collective experience of building a distributed system, in that it puts responsibility on developers to decide how they want an app to interoperate with others in the network, and favors configuration and extensibility instead of making assumptions about the network setup.
diff --git a/4-architecture.md b/4-architecture.md
index 3d5344924..bbd93ca53 100644
--- a/4-architecture.md
+++ b/4-architecture.md
@@ -1,6 +1,9 @@
 4 Architecture
 ==============
 
+| ⚠️ Warning: this section is incomplete, and parts of it are out of date. Please see [this issue](https://github.com/libp2p/specs/issues/156) to track progress on improving it. ⚠️ |
+| --- |
+
 `libp2p` was designed around the Unix Philosophy of creating small components that are easy to understand and test. These components should also be able to be swapped in order to accommodate different technologies or scenarios and also make it feasible to upgrade them over time.
 
 Although different peers can support different protocols depending on their capabilities, any peer can act as a dialer and/or a listener for connections from other peers, connections that once established can be reused from both ends, removing the distinction between clients and servers.
diff --git a/6-interfaces.md b/6-interfaces.md
index f6719b832..053ab7fb0 100644
--- a/6-interfaces.md
+++ b/6-interfaces.md
@@ -1,6 +1,9 @@
 6 Interfaces
 ============
 
+| ⚠️ Warning: this section is incomplete, and parts of it are out of date. Please see [this issue](https://github.com/libp2p/specs/issues/156) to track progress on improving it. ⚠️ |
+| --- |
+
 `libp2p` is a collection of several protocols working together to offer a common solid interface that can talk with any other network addressable process. This is made possible by shimming currently existing protocols and implementations into a set of explicit interfaces: Peer Routing, Discovery, Stream Muxing, Transports, Connections and so on.
 
 ## 6.1 libp2p
diff --git a/7-properties.md b/7-properties.md
index ea419de25..379ad21df 100644
--- a/7-properties.md
+++ b/7-properties.md
@@ -1,6 +1,9 @@
 7 Properties
 ============
 
+| ⚠️ Warning: this section is incomplete, and parts of it are out of date. Please see [this issue](https://github.com/libp2p/specs/issues/156) to track progress on improving it. ⚠️ |
+| --- |
+
 ## 7.1 Communication Model - Streams
 
 The Network layer handles all the problems of connecting to a peer, and exposes