diff --git a/doc/man_docs.go b/doc/man_docs.go
index 942b0aad..f21d8395 100644
--- a/doc/man_docs.go
+++ b/doc/man_docs.go
@@ -18,6 +18,7 @@ import (
 	"fmt"
 	"io"
 	"os"
+	"path/filepath"
 	"sort"
 	"strings"
 	"time"
@@ -46,8 +47,8 @@ func GenManTree(cmd *cobra.Command, header *GenManHeader, dir string) error {
 	}
 	needToResetTitle := header.Title == ""
 
-	filename := cmd.CommandPath()
-	filename = dir + strings.Replace(filename, " ", "-", -1) + ".1"
+	basename := strings.Replace(cmd.CommandPath(), " ", "_", -1) + ".1"
+	filename := filepath.Join(dir, basename)
 	f, err := os.Create(filename)
 	if err != nil {
 		return err
diff --git a/doc/man_docs.md b/doc/man_docs.md
index 3408c301..5fe957a3 100644
--- a/doc/man_docs.md
+++ b/doc/man_docs.md
@@ -7,6 +7,7 @@ package main
 
 import (
 	"github.com/spf13/cobra"
+	"github.com/spf13/cobra/doc"
 )
 
 func main() {
@@ -18,7 +19,7 @@ func main() {
 		Title: "MINE",
 		Section: "3",
 	}
-	cmd.GenManTree(header, "/tmp")
+	doc.GenManTree(cmd, header, "/tmp")
 }
 ```
 
diff --git a/doc/md_docs.go b/doc/md_docs.go
index 666e9495..fa136318 100644
--- a/doc/md_docs.go
+++ b/doc/md_docs.go
@@ -17,6 +17,7 @@ import (
 	"fmt"
 	"io"
 	"os"
+	"path/filepath"
 	"sort"
 	"strings"
 	"time"
@@ -156,8 +157,8 @@ func GenMarkdownTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHa
 		}
 	}
 
-	filename := cmd.CommandPath()
-	filename = dir + strings.Replace(filename, " ", "_", -1) + ".md"
+	basename := strings.Replace(cmd.CommandPath(), " ", "_", -1) + ".md"
+	filename := filepath.Join(dir, basename)
 	f, err := os.Create(filename)
 	if err != nil {
 		return err
diff --git a/doc/md_docs.md b/doc/md_docs.md
index da35f92e..0c3b96e2 100644
--- a/doc/md_docs.md
+++ b/doc/md_docs.md
@@ -1,5 +1,26 @@
 # Generating Markdown Docs For Your Own cobra.Command
 
+Generating man pages from a cobra command is incredibly easy. An example is as follows:
+
+```go
+package main
+
+import (
+	"github.com/spf13/cobra"
+	"github.com/spf13/cobra/doc"
+)
+
+func main() {
+	cmd := &cobra.Command{
+		Use:   "test",
+		Short: "my test program",
+	}
+	doc.GenMarkdownTree(cmd, "/tmp")
+}
+```
+
+That will get you a Markdown document `/tmp/test.md`
+
 ## Generate markdown docs for the entire command tree
 
 This program can actually generate docs for the kubectl command in the kubernetes project
@@ -11,13 +32,15 @@ import (
 	"io/ioutil"
 	"os"
 
-	"github.com/GoogleCloudPlatform/kubernetes/pkg/kubectl/cmd"
-	"github.com/spf13/cobra/cobra"
+	kubectlcmd "k8s.io/kubernetes/pkg/kubectl/cmd"
+	cmdutil "k8s.io/kubernetes/pkg/kubectl/cmd/util"
+
+	"github.com/spf13/cobra/doc"
 )
 
 func main() {
-	kubectl := cmd.NewFactory(nil).NewKubectlCommand(os.Stdin, ioutil.Discard, ioutil.Discard)
-	doc.GenMarkdownTree(kubectl, "./")
+	cmd := kubectlcmd.NewKubectlCommand(cmdutil.NewFactory(nil), os.Stdin, ioutil.Discard, ioutil.Discard)
+	doc.GenMarkdownTree(cmd, "./")
 }
 ```
 
@@ -40,13 +63,13 @@ Both `GenMarkdown` and `GenMarkdownTree` have alternate versions with callbacks
 
 ```go
 func GenMarkdownTreeCustom(cmd *Command, dir string, filePrepender, linkHandler func(string) string) error {
-    //...
+	//...
 }
 ```
 
 ```go
 func GenMarkdownCustom(cmd *Command, out *bytes.Buffer, linkHandler func(string) string) error {
-    //...
+	//...
 }
 ```