usability: Need to add documentation for a binary in three different places

[kevinburke]

If I'm shipping a Go binary, generally, I need to add documentation in three different places:

• a README or README.md file, for people visiting the project via Github. This contains usage information and usually also installation information

• in doc.go or similar, so it appears via godoc. Some go tools document this well, but many tools fall down on the docs here:

  • https://godoc.org/github.com/golang/dep/cmd/dep
  • https://godoc.org/golang.org/x/build/maintner/maintnerd
  • https://godoc.org/golang.org/x/build/cmd/gopherbot
  • https://godoc.org/github.com/kubernetes/kubernetes/cmd/kubectl
  • https://godoc.org/github.com/moby/moby/cmd/docker
  • https://godoc.org/github.com/spf13/hugo

• in flag.Usage, so it looks nice when printed at the command line, and shows you the various arguments you can run.

It's a shame that maintainers have to more or less write the same docs in triplicate, and a bad experience for our users when they forget to do so in one or more of the places above.

I also wonder if this discourages contribution, when people get to a Github source code page and the results are clearly not formatted for browsing on that site.

I'm wondering what we can do to ease the burden on maintainers, or make it easy to copy docs from one place to another. I understand that the audiences for each documentation place overlap in parts and don't overlap in other parts, but I imagine some docs are better than nothing. Here are some bad ideas:

• If a main function has no package docs, but modifies flag.CommandLine, godoc could call flag.PrintDefaults, or call the binary with -h and then print the result. Note the godoc docs linked above manually copy the output from flag.PrintDefaults and it occasionally gets out of sync.

• If a main function has no package docs but has a README.md, godoc could format README.md and ignore the parts of the markdown spec that we don't want to implement.

• We could try to get Github to understand and display Go code, the same way it can currently display a number of formats like Restructured Text, ASCIIDOC, Creole, RDoc, textile and others.

[bradfitz]

Didn't somebody once write a tool to auto-generate a README.md file from the Go program's source code?

[ckaznocha]

@bradfitz is this the one you're thinking of godocdown?

I tend to put my docs in doc.go then use godocdown to generate the README to get me started but it ends up feeling a bit redundant with godoc.org.

[bradfitz]

I forget. That might've been the one I saw. I've never used one.

[lrewega]

For going the other way there is: sectioneight/md-to-godoc

[dmitshur]

godoc could ... call the binary with -h and then print the result.

You'd need to do this in a safe execution environment, since you're executing arbitrary binaries (any user code can be inside flag.Usage). I've wanted to add a tab to gotools.org that does that, but it hasn't happened.

We could try to get Github to understand and display Go code, the same way it can currently display a number of formats like Restructured Text, ASCIIDOC, Creole, RDoc, textile and others.

That could be really nice. If GitHub would just display a package summary via godoc when README.md isn't present, I wouldn't have to keep generating them. But it also sounds far fetched/a lot of work to make it happen.

Didn't somebody once write a tool to auto-generate a README.md file from the Go program's source code?

I generate all of my Go package README.md files (and some other boilerplate, like .travis.yml) with gorepogen. See an example here. But it's pretty much customized exactly for my preferences. As I understand, people tend to make their own version of such a tool for their own needs.

[dolanor]

I was thinking about that lately.
It's true that the ideal would be that Github render the documentation from the source. Or at least link to godoc with the right URL. I don't know if it's so far fetched, it's just another format.
But for me go should be able to generate the godoc from the flags of a binary in the first place. (at least for the official "flag" package).

[dmitshur]

But for me go should be able to generate the godoc from the flags of a binary in the first place. (at least for the official "flag" package).

Running with -help does list all flags that have been registered, along with their descriptions and default values, etc. This is automatic.

The only thing one needs to do in flag.Usage which is custom is to describe the command.

Perhaps someone can make a tool, which can be invoked via go generate, that parses godoc of a command and generates a corresponding flag.Usage implementation.

[seankhliao]

I believe this is now resolved with a combination of: pkgsite rendering readmes and the ability to use embed to embed/extract parts of the readme for use in command line help.