diff --git a/README.md b/README.md
index 1c7e6bd80a9df3c714279ec50a9b5fdbde0fb8da..c05fc29ba3bcdd669c639faebbdc26f4f554d6d7 100644
--- a/README.md
+++ b/README.md
@@ -5,14 +5,13 @@ A re-implementation of BGP, IS-IS and OSPF in go. We value respect and robustnes
 [![Build Status](https://travis-ci.org/bio-routing/bio-rd.svg?branch=master)](https://travis-ci.org/bio-routing/bio-rd)
 [![Coverage Status](https://coveralls.io/repos/bio-routing/bio-rd/badge.svg?branch=master&service=github)](https://coveralls.io/github/bio-routing/bio-rd?branch=master)
 [![Go ReportCard](http://goreportcard.com/badge/bio-routing/bio-rd)](http://goreportcard.com/report/bio-routing/bio-rd)
+[![Go Doc](https://godoc.org/github.com/bio-routing/bio-rd?status.svg)](https://godoc.org/github.com/bio-routing/bio-rd)
 
-Building
-========
+## Building
 
 We use [Bazel](https://bazel.io) to build bio-rd.
 
-Build
------
+### Build
 
     bazel build //:bio-rd
     bazel-bin/linux_amd64_stripped/bio-rd -arguments go -here
@@ -21,14 +20,11 @@ or
 
     bazel run //:bio-rd -- -arguments go -here
 
-Run Tests
----------
+### Run Tests
 
     bazel test //...
 
-
-Update Bazel BUILD files
-------------------------
+### Update Bazel BUILD files
 
 To regenerate BUILD files (for both the project and vendored libraries), you will need to run the following:
 
@@ -36,13 +32,17 @@ To regenerate BUILD files (for both the project and vendored libraries), you wil
 
 Be sure to commit the changes.
 
-Update vendor/dependencies
----------------------------
+### Update vendor/dependencies
 
-After updating Gopkg.toml, run
+#### build `dep`
 
     bazel build //vendor/github.com/golang/dep/cmd/dep
-    bazel-bin/vendor/github.com/golang/dep/cmd/dep/linux_amd64_stripped/dep use
-    # hack: dep of dep gives us these, and it breaks gazelle
+
+#### Update vendor/add dependencies
+
+    bazel-bin/vendor/github.com/golang/dep/cmd/dep/linux_amd64_stripped/dep ensure
+
+dep of dep breaks gazelle. Therefore execute the following commands after updating Gopkg.toml
+
     rm -rf vendor/github.com/golang/dep/cmd/dep/testdata
     rm -rf vendor/github.com/golang/dep/internal/fs/testdata/symlinks/dir-symlink