diff --git a/middleware/middleware.go b/middleware/middleware.go
index 44e806dde..4ceda5940 100644
--- a/middleware/middleware.go
+++ b/middleware/middleware.go
@@ -18,9 +18,15 @@ type (
 	// and/or error.
 	//
 	// If ServeDNS writes to the response body, it should return a status
-	// code of 0. This signals to other handlers above it that the response
-	// body is already written, and that they should not write to it also.
-	// TODO(miek): explain return codes better.
+	// code. If the status code is not one of the following:
+	// * SERVFAIL (dns.RcodeServerFailure)
+	// * REFUSED (dns.RecodeRefused)
+	// * FORMERR (dns.RcodeFormatError)
+	// * NOTIMP (dns.RcodeNotImplemented)
+	//
+	// CoreDNS assumes *no* reply has yet been written. All other response
+	// codes signal other handlers above it that the response message is
+	// already written, and that they should not write to it also.
 	//
 	// If ServeDNS encounters an error, it should return the error value
 	// so it can be logged by designated error-handling middleware.
diff --git a/placeholder.md b/placeholder.md
deleted file mode 100644
index efe0033eb..000000000
--- a/placeholder.md
+++ /dev/null
@@ -1,30 +0,0 @@
-# Placeholders
-
-Some directives allow you to use placeholders in your Caddyfile to fill out a value differently for every request. For example, the value {path} would be replaced by the path portion of the request URL. These are also called replaceable values.
-These placeholders only work on directives that support them. Check the documentation for your directive to see if placeholders are supported.
-Request Placeholders
-
-These values are obtained from the request.
-
-* {dir} - The directory of the requested file (from request URI)
-* { file} - The name of the requested file (from request URI)
-* {fragment} - The last part of the URL starting with "#"
-* {>Header} - Any request header, where "Header" is the header field name
-* {host} - The host portion of the request
-* {method} - The request method (GET, POST, etc.)
-* {path} - The path portion of the URL (does not include query string or fragment)
-* {port} - The client's port
-* {proto} - The protocol string (e.g. "HTTP/1.1")
-* {query} - The query string portion of the URL, without leading "?"
-* {remote} - The client's IP address
-* {scheme} - The protocol/scheme used (usually http or https)
-* {uri} - The request URI (includes path, query string, and fragment)
-* {when} - Timestamp in the format 02/Jan/2006:15:04:05 -0700
-
-## Response Placeholders
-
-These values are obtained from the response, and are only implemented with some directives. Make sure your directive supports response placeholders before attempting to use them.
-
-* {latency} - Approximate time the server spent handling the request
-* {size} - The size of the response body
-* {status} - The HTTP status code of the response