New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create structure for managing docs #331

Closed
sdboyer opened this Issue Mar 14, 2017 · 14 comments

Comments

Projects
None yet
7 participants
@sdboyer
Copy link
Member

sdboyer commented Mar 14, 2017

(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

This comment has been minimized.

Copy link
Member

sdboyer commented Mar 14, 2017

maybe this is of some interest to @spf13 😄

@spf13

This comment has been minimized.

Copy link

spf13 commented Mar 19, 2017

@sdboyer

This comment has been minimized.

Copy link
Member

sdboyer commented Mar 20, 2017

@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

This comment has been minimized.

Copy link

spf13 commented Mar 20, 2017

@sdboyer

This comment has been minimized.

Copy link
Member

sdboyer commented Mar 20, 2017

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

This comment has been minimized.

Copy link

zacps commented Mar 21, 2017

I'd also like man pages for Unix systems.

@velovix

This comment has been minimized.

Copy link

velovix commented Apr 18, 2017

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

This comment has been minimized.

Copy link

zacps commented Apr 18, 2017

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

@sdboyer

This comment has been minimized.

Copy link
Member

sdboyer commented Apr 18, 2017

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

This comment has been minimized.

Copy link
Collaborator

jmank88 commented Apr 18, 2017

@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

This comment has been minimized.

Copy link
Member

sdboyer commented Apr 18, 2017

@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

This comment has been minimized.

Copy link
Collaborator

jmank88 commented Apr 18, 2017

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

This comment has been minimized.

Copy link

daenney commented Apr 18, 2017

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

This comment has been minimized.

Copy link
Collaborator

carolynvs commented Apr 18, 2017

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.

@carolynvs carolynvs referenced this issue Apr 19, 2017

Merged

Add a FAQ #401

daenney added a commit to daenney/dep that referenced this issue Apr 21, 2017

docs: Create a FAQ
Based on a quick chat with @sdboyer we're going to start with a FAQ in
which we can collect people's questions. Whenever there's a recurring
question around `dep` please send a PR to the FAQ. This will serve as a
source of data for what the actual documentation should include.

This is a first step in resolving golang#331.

daenney added a commit to daenney/dep that referenced this issue Apr 21, 2017

docs: Create a FAQ
Based on a quick chat with @sdboyer we're going to start with a FAQ in
which we can collect people's questions. Whenever there's a recurring
question around `dep` please send a PR to the FAQ. This will serve as a
source of data for what the actual documentation should include.

This is a first step in resolving golang#331.

@carolynvs carolynvs referenced this issue Nov 12, 2017

Closed

[WIP] Prototype doc site #1369

0 of 5 tasks complete

@sdboyer sdboyer referenced this issue Jan 1, 2018

Merged

[WIP] Add a mountain of docs #1499

7 of 7 tasks complete
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment