1 files changed, 29 insertions, 1 deletions
diff --git a/middleware.md b/middleware.md
index 711d9c4ad..cef243198 100644
--- a/middleware.md
+++ b/middleware.md
@@ -1,4 +1,6 @@
-# Writing middleware
+# Middleware
+
+## Writing Middleware
 
 From the Caddy docs:
 
@@ -26,3 +28,29 @@ So CoreDNS treats:
 
 as special and will then assume nothing has written to the client. In all other cases it is assumes
 something has been written to the client (by the middleware).
+
+## Hooking it up
+
+TODO(miek): text here on how to hook up middleware.
+
+# Documentation
+
+Each middleware should have a README.md explaining what the middleware does and how it is
+configured. The file should have the following layout:
+
+* Title: use the middleware's name
+* Subsection titled: "Syntax"
+* Subsection titled: "Examples"
+
+More sections are of course possible.
+
+## Style
+
+We use the Unix manual page style:
+
+* The name of middleware in the running text should be italic: *middleware*.
+* all CAPITAL: user supplied argument, in the running text references this use strong text: `**`:
+  **EXAMPLE**.
+* Optional text: in block quotes: `[optional]`.
+* Use three dots to indicate multiple options are allowed: `arg...`.
+* Item used literal: `literal`.