diff --git a/README.md b/README.md
index f2811d847..0834f94e1 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,8 @@
 # CoreDNS
 
+ [![Documentation](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square)](https://godoc.org/github.com/miekg/coredns)
+ [![Build Status](https://img.shields.io/travis/miekg/coredns.svg?style=flat-square&label=build)](https://travis-ci.org/miekg/coredns)
+
 CoreDNS is a DNS server that started as a fork of [Caddy](https://github.com/mholt/caddy/). It has the
 same model: it chains middleware. In fact it's so similar that CoreDNS is now a server type plugin for
 Caddy.
diff --git a/core/coredns.go b/core/coredns.go
index eb6e204d6..8b53c0dda 100644
--- a/core/coredns.go
+++ b/core/coredns.go
@@ -1,3 +1,4 @@
+// Package core registers the server and all plugins we support.
 package core
 
 import (
diff --git a/core/dnsserver/server.go b/core/dnsserver/server.go
index 9f2a8a024..ffd5558a3 100644
--- a/core/dnsserver/server.go
+++ b/core/dnsserver/server.go
@@ -1,3 +1,5 @@
+// Package DNS server implements all the interfaces from Caddy, so that
+// CoreDNS can be a servertype plugin.
 package dnsserver
 
 import (
diff --git a/coremain/run.go b/coremain/run.go
index 7552074c1..8d73f6664 100644
--- a/coremain/run.go
+++ b/coremain/run.go
@@ -1,3 +1,4 @@
+// Package coremain contains the functions for starting CoreDNS.
 package coremain
 
 import (
diff --git a/middleware/bind/bind.go b/middleware/bind/bind.go
index ac27c993b..bd3c32b51 100644
--- a/middleware/bind/bind.go
+++ b/middleware/bind/bind.go
@@ -1,3 +1,4 @@
+// Package bind allows binding to a specific interface instead of bind to all of them.
 package bind
 
 import "github.com/mholt/caddy"
diff --git a/middleware/chaos/chaos.go b/middleware/chaos/chaos.go
index dc80f47a9..6d83f5dda 100644
--- a/middleware/chaos/chaos.go
+++ b/middleware/chaos/chaos.go
@@ -1,3 +1,4 @@
+// Package chaos implements a middleware that answer to 'CH version.bind TXT' type queries.
 package chaos
 
 import (
diff --git a/middleware/dnssec/dnssec.go b/middleware/dnssec/dnssec.go
index 9dcb6e434..06c2e46bd 100644
--- a/middleware/dnssec/dnssec.go
+++ b/middleware/dnssec/dnssec.go
@@ -1,3 +1,5 @@
+// Package dnssec implements a middleware that signs responses on-the-fly using
+// NSEC black lies.
 package dnssec
 
 import (
diff --git a/middleware/etcd/etcd.go b/middleware/etcd/etcd.go
index 09cd5ba55..d13c7c031 100644
--- a/middleware/etcd/etcd.go
+++ b/middleware/etcd/etcd.go
@@ -1,4 +1,4 @@
-// Package etcd provides the etcd backend.
+// Package etcd provides the etcd backend middleware.
 package etcd
 
 import (
diff --git a/middleware/etcd/msg/service.go b/middleware/etcd/msg/service.go
index bd8055289..9250cb634 100644
--- a/middleware/etcd/msg/service.go
+++ b/middleware/etcd/msg/service.go
@@ -1,3 +1,4 @@
+// Package msg defines the Service structure which is used for service discovery.
 package msg
 
 import (
diff --git a/middleware/file/file.go b/middleware/file/file.go
index 5dc63a292..b1136c7db 100644
--- a/middleware/file/file.go
+++ b/middleware/file/file.go
@@ -1,3 +1,4 @@
+// Package file implements a file backend.
 package file
 
 import (
diff --git a/middleware/health/health.go b/middleware/health/health.go
index 513791688..08aa847d2 100644
--- a/middleware/health/health.go
+++ b/middleware/health/health.go
@@ -1,3 +1,4 @@
+// Package health implements an HTTP handler that responds to health checks.
 package health
 
 import (
diff --git a/middleware/kubernetes/kubernetes.go b/middleware/kubernetes/kubernetes.go
index 3f8b539c7..853cc311a 100644
--- a/middleware/kubernetes/kubernetes.go
+++ b/middleware/kubernetes/kubernetes.go
@@ -17,8 +17,8 @@ import (
 	"github.com/miekg/dns"
 	"k8s.io/kubernetes/pkg/api"
 	unversionedapi "k8s.io/kubernetes/pkg/api/unversioned"
-	unversionedclient "k8s.io/kubernetes/pkg/client/unversioned"
 	"k8s.io/kubernetes/pkg/client/restclient"
+	unversionedclient "k8s.io/kubernetes/pkg/client/unversioned"
 	"k8s.io/kubernetes/pkg/client/unversioned/clientcmd"
 	clientcmdapi "k8s.io/kubernetes/pkg/client/unversioned/clientcmd/api"
 	"k8s.io/kubernetes/pkg/labels"
diff --git a/middleware/loadbalance/loadbalance.go b/middleware/loadbalance/loadbalance.go
index 57f1f9174..59aad8a4f 100644
--- a/middleware/loadbalance/loadbalance.go
+++ b/middleware/loadbalance/loadbalance.go
@@ -1,3 +1,4 @@
+// Package loadbalance shuffles A and AAAA records.
 package loadbalance
 
 import (
diff --git a/middleware/metrics/metrics.go b/middleware/metrics/metrics.go
index b7473a00e..d8af7f7c5 100644
--- a/middleware/metrics/metrics.go
+++ b/middleware/metrics/metrics.go
@@ -1,3 +1,5 @@
+// Package metrics implement a handler and middleware that provides Prometheus
+// metrics.
 package metrics
 
 import (
diff --git a/middleware/pkg/dnsrecorder/recorder.go b/middleware/pkg/dnsrecorder/recorder.go
index 9bf045e91..a4e9ec56b 100644
--- a/middleware/pkg/dnsrecorder/recorder.go
+++ b/middleware/pkg/dnsrecorder/recorder.go
@@ -1,3 +1,4 @@
+// Package dnsrecorder allows you to record a DNS response when it is send to the client.
 package dnsrecorder
 
 import (
diff --git a/middleware/pkg/dnsutil/doc.go b/middleware/pkg/dnsutil/doc.go
new file mode 100644
index 000000000..75d1e8c7a
--- /dev/null
+++ b/middleware/pkg/dnsutil/doc.go
@@ -0,0 +1,2 @@
+// Package dnsutil contains DNS related helper functions.
+package dnsutil
diff --git a/middleware/pkg/edns/edns.go b/middleware/pkg/edns/edns.go
index 6704066b0..d32737840 100644
--- a/middleware/pkg/edns/edns.go
+++ b/middleware/pkg/edns/edns.go
@@ -1,3 +1,4 @@
+// Package edns provides function usefull for adding/inspecting OPT records to/in messages.
 package edns
 
 import (
diff --git a/middleware/pkg/storage/fs.go b/middleware/pkg/storage/fs.go
index 4cbf526ae..a6ea181f1 100644
--- a/middleware/pkg/storage/fs.go
+++ b/middleware/pkg/storage/fs.go
@@ -1,3 +1,4 @@
+// Package storage abstracts away where middleware can store assests (zones, keys, etc).
 package storage
 
 import (
diff --git a/middleware/pprof/pprof.go b/middleware/pprof/pprof.go
index f2f580d76..aef834a68 100644
--- a/middleware/pprof/pprof.go
+++ b/middleware/pprof/pprof.go
@@ -1,3 +1,5 @@
+// Package pprof implement a debug endpoint for getting profiles using the
+// go pprof tooling.
 package pprof
 
 import (
diff --git a/middleware/secondary/secondary.go b/middleware/secondary/secondary.go
index c0d101f7c..6a95230f4 100644
--- a/middleware/secondary/secondary.go
+++ b/middleware/secondary/secondary.go
@@ -1,3 +1,4 @@
+// Package secondary implements a secondary middleware.
 package secondary
 
 import "github.com/miekg/coredns/middleware/file"
diff --git a/middleware/test/doc.go b/middleware/test/doc.go
new file mode 100644
index 000000000..e2f90262b
--- /dev/null
+++ b/middleware/test/doc.go
@@ -0,0 +1,2 @@
+// Package test contains helper functions for writing middleware tests.
+package test
diff --git a/middleware/whoami/whoami.go b/middleware/whoami/whoami.go
index 4de9a9cdb..ccf8aefe1 100644
--- a/middleware/whoami/whoami.go
+++ b/middleware/whoami/whoami.go
@@ -1,3 +1,5 @@
+// Package whoami implements a middleware that returns details about the resolving
+// querying it.
 package whoami
 
 import (
diff --git a/request/request.go b/request/request.go
index 004b87696..999acc256 100644
--- a/request/request.go
+++ b/request/request.go
@@ -1,3 +1,5 @@
+// Package requests abstract a client's request so that all middleware
+// will handle them in an unified way.
 package request
 
 import (
diff --git a/test/doc.go b/test/doc.go
new file mode 100644
index 000000000..ba09e8772
--- /dev/null
+++ b/test/doc.go
@@ -0,0 +1,2 @@
+// Package test contains function and types useful for writing tests
+package test