Create structure for managing docs

[sdboyer]

(Inspired by @carolynvs' comment - #328 (comment))

We really need more extensive docs for dep than what belongs in CLI helptext. But we also don't want to have that classic problem where the docs and the code gets updated separately, leaving the docs constantly out of date. So, we need two things:

1. A docs generator that can automatically set up a site from docs that live in the repo itself
2. A policy that we don't merge in anything without creating or updating corresponding docs, as needed

Eventually we'll probably want at least some of these docs to be transferrable into official/toolchain docs, but IMO that shouldn't hinder us overmuch right now.

There's a plethora of options to choose from for the first item - maybe something hugo-based, being that we're about as deep in gopherdom as you can get with this project? idk. It'd be great if someone wanted to champion this. Doing so would probably entail setting up both the mechanism and writing some basic guidelines for how and where to contribute to docs.

(It should go without saying, but just in case - this would be for broader docs over and above what godoc provides).

[sdboyer]

maybe this is of some interest to @spf13 😄

[spf13]

I am interested. What did you have in mind @samboyer?

…

On Tue, Mar 14, 2017 at 12:45 PM sam boyer ***@***.***> wrote: maybe this is of some interest to @spf13 <https://github.com/spf13> 😄 — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#331 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAKlZIZm4eqXyacx_Onehc44b2o1XJLrks5rlsQTgaJpZM4Mc18E> .

[sdboyer]

@spf13 oh, that's great! 🎉

I don't have a lot of thoughts yet about how to organize the docs themselves, or what all should be in them. For now, I think the big thing right now is just setting up a mechanism for automatically generating them from (I'd imagine) markdown files in a subdirectory, and then maybe pushing them back to a gh-pages branch. That way we can ensure they're updated as the project evolves.

idk if this is something people often use hugo for or not, but it seemed like a possibility. I figure that, once we have a rough mechanism in place, the information in there take shape organically.

Is that enough to start with?

[spf13]

Yes. Hugo is very commonly used in this manner and there's a few good tutorials how to set that up on the Hugo site. Another set of hosting options are netlify, Google Cloud or AWS which IMHO are all better than Github pages. The Hugo project uses a docs subdirectory and builds the site out of that. It has the advantage of always being in sync with the releases. Let me know how I can help. I'm happy to do whatever is needed.

…

On Mon, Mar 20, 2017 at 12:22 PM sam boyer ***@***.***> wrote: @spf13 <https://github.com/spf13> oh, that's great! 🎉 I don't have a lot of thoughts yet about how to organize the docs themselves, or what all should be in them. For now, I think the big thing right now is just setting up a mechanism for automatically generating them from (I'd imagine) markdown files in a subdirectory, and then maybe pushing them back to a gh-pages branch. That way we can ensure they're updated as the project evolves. idk if this is something people often use hugo for or not, but it seemed like a possibility. I figure that, once we have a rough mechanism in place, the information in there take shape organically. Is that enough to start with? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#331 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAKlZLCAKSBWJ-aRWFZCwIb6HxPKOtHVks5rnqfEgaJpZM4Mc18E> .

[sdboyer]

Great! Right now we're long on well-defined work to do, and short on people/time to actually do it. IMO, the most helpful thing right now would be just doing that setup.

[zacps]

I'd also like man pages for Unix systems.

[velovix]

Man pages will be a complicated problem. Before Dep is merged into the toolchain, I don't think anybody will be installing it in any way other than go get. After Dep is merged into the toolchain, we'll be dealing with the fact that the Go command itself doesn't have man pages. There's an issue for this, which happens to be the oldest open issue on the project, so I don't see that changing anytime soon.

[zacps]

Unfortunate, you're right that there doesn't seem to be anything we can do about it.

[sdboyer]

So, on considering this further, and discussing a bit on reddit, I think the best course of action is probably to prep docs in the final form we hope them to take - HTML files that live on golang.org.

I don't know how those files are generated (oi, I hope they're not hand-written), but we should at least look at reusing that mechanism for our purposes now.

[jmank88]

@sdboyer Following that trail...
This documentation: https://golang.org/cmd/go/
Appears to generated from this go file: https://golang.org/src/cmd/go/alldocs.go on github
Which is generated by this process: https://golang.org/src/cmd/go/mkalldocs.sh on github, which looks like a neat trick
Edit: More relevant files here: https://github.com/golang/go/tree/master/src/cmd/go/internal/help

[sdboyer]

@jmank88 thanks for chasing that down. I'm kinda worried about that just to the extent that it might prevent us from adding helpful explanatory images/diagrams, but c'est la vie.

Is everything, even the spec, generated in this sort of way?

[jmank88]

Looks like doc/go_spec.html is hand written golang/go@94b6011 , though I'm not sure how much variance from godoc style there is.
Edit: But there are certainly images

[daenney]

What would be the advantage of using something like Hugo (to push back to gh-pages or somewhere else) over maintaining a docs/ folder that can be configured to automatically be the source of GitHub Pages (no gh-pages needed)? This keeps it really simple and means that, without any further moving parts that could break, a commit to docs/ on master is almost instantly reflected on the project's site.

Using subdirectories you can equally support multiple languages and release versions and update whatever the index page of the documents site ends up being to pointing to the latest release docs by default.

[carolynvs]

I was going to suggest using /docs as well. It's quite helpful to be able to have a PR add a feature, tests, and update the docs all at once.