ubclaunchpad / rocket

:rocket: Slack bot, team management, and onboarding system for UBC Launch Pad - superseded by Rocket2: https://github.com/ubclaunchpad/rocket2
2 stars 0 forks source link

Update godocs #82

Closed bobheadxi closed 6 years ago

bobheadxi commented 6 years ago

godocs are a pretty nice way of getting an overview of a go project, and at https://godoc.org/github.com/ubclaunchpad/rocket things looking pretty scant right now

I'll put in a PR with some brief godoc summaries

Example: https://godoc.org/github.com/ubclaunchpad/inertia

bobheadxi commented 6 years ago

I think we can clear up some of the README too in favour of godocs. For example:

https://github.com/ubclaunchpad/rocket#commands could be replaced by https://godoc.org/github.com/ubclaunchpad/rocket/cmd#Command

https://github.com/ubclaunchpad/rocket#options could be replaced by https://godoc.org/github.com/ubclaunchpad/rocket/cmd#Option

etc. etc. - thoughts @bfbachmann ? also wondering if we should move the deployment instructions back into the wiki, or just remove the wiki, because one of the two will inevitably end up out of date

bfbachmann commented 6 years ago

tl;dr Move code-related docs to Godoc, put all other docs in the README.

I think moving technical docs from the README to Godoc is an excellent idea, but I wouldn't move deployment instructions to the wiki for a two reasons:

  1. Keeping those instructions in the README means they are version controlled and can be reviewed in the PR process before they are updated, so they're more likely to be kept up-to-date and accurate.
  2. They're easier to find since they're on the first page you see when you open the repo

I think we should just get rid of the wiki and just move anything on there to the README, since nobody actually reads GitHub wikis unless they're told to, and because of the two reasons I mentioned above.

bobheadxi commented 6 years ago

That's a good idea, I'll move everything out of the wiki when i get to this ticket.

bobheadxi commented 6 years ago

Removed wiki pages that are now on README and godocs are working nicely now after #83:

https://godoc.org/github.com/ubclaunchpad/rocket