diff --git a/cmd/ysvd/main.go b/cmd/ysvd/main.go
index 7e7aafd..607d5ef 100644
--- a/cmd/ysvd/main.go
+++ b/cmd/ysvd/main.go
@@ -1,5 +1,40 @@
/*
-command ysvd implements the
+ysvd, a webserver for hosting go get vanity urls.
+
+The go get command searches for the following header when searching for
+packages:
+
+
+
+this is simply a service for aggregating a collection of prefix, vcs, and
+repo-root tuples, and serving the appropriate header over http. For more
+information please refer to the documentation for the go tool found at
+https://golang.org/cmd/go/#hdr-Remote_import_paths
+
+API
+
+Assume an instance of ysvd at example.org. In order to add a package
+example.org/foo that points at bitbucket.org/example/foo (a mercurial
+repository) POST the following json object:
+
+ {
+ "vcs": "mercurial",
+ "repo": "https://bitbucket.org/example/foo"
+ }
+
+to https://example.org/foo.
+
+Doing so, then visiting https://example.org/foo?go-get=1 will yield a header
+that looks like:
+
+
+
+
+
+The json object sent to server can have two fields: "repo" and "vcs". "repo" is
+required; leaving off the "vcs" member defaults to "git".
+
+Naming
The "ysv" in ysvd stands for You're so Vain, the song by Carly Simon.
*/
diff --git a/doc.go b/doc.go
index aa568f3..12ee4d2 100644
--- a/doc.go
+++ b/doc.go
@@ -1,27 +1 @@
-/*
-Package vain implements a vanity service for use by the the go tool
-
-From the documentation for the go tool, it searches for the following header
-when searching for packages:
-
-
-
-this is simply a service for aggregating a collection of prefix, vcs, and
-repo-root tuples, and serving the appropriate header over http.
-
-API
-
-In order to add a new package POST a json object to the following route:
-
- POST /
-
-A sample json object:
-
- {
- "vcs": "mercurial",
- "repo": "https://s.mcquay.me/sm/vain"
- }
-
-"repo" is required; leaving off the "vcs" member defaults to "git".
-*/
package vain