Skip to content
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

proposal: create contribution guidelines for technical writers #33323

Closed
nathany opened this issue Jul 27, 2019 · 9 comments
Closed

proposal: create contribution guidelines for technical writers #33323

nathany opened this issue Jul 27, 2019 · 9 comments

Comments

@nathany
Copy link
Contributor

nathany commented Jul 27, 2019

(notes from GopherCon Community Day)

  • Technical writer friendly workflow (e.g. edit on GitHub to submit a pull request)
  • The kinds of documentation (tutorial, reference, quick reference, blog posts)
  • Style guide or link to one

Also:

@gopherbot gopherbot added this to the Proposal milestone Jul 27, 2019
@mvdan
Copy link
Member

mvdan commented Jul 28, 2019

I don't think the current contribution guide is exclusively about code, though. For example, the main repository has a doc/ folder, and there are files like src/cmd/compile/README.md which serve as technical documentation.

I think it's fair to highlight how to contribute documentation, but we should also be clear about where each kind of documentation lives.

@rsc
Copy link
Contributor

rsc commented Oct 9, 2019

This proposal seems like it has a good idea in it, but without concrete detail about what would happen it's hard to evaluate. In this sense it's a little like #32741. It seems like maybe we should close in the absence of a more concrete plan.

@nathany
Copy link
Contributor Author

nathany commented Oct 12, 2019

"How you can help" could be changed to include "Contributing code and documentation". That would be easy to do.

One concern is that technical writers may not be well versed with git. The current guidelines are very oriented towards developers, with initial steps using the command line to install a git plugin. I don't think there is a way around that though, because even if GitHub's tools are used ("Fork this project and edit this file") to submit the initial pull request, any followup changes would require Gerrit, correct?

The other concern is that we don't have any sort of style guide for documentation. I don't have anything concrete for that though.

@toothrot Anything else to add?

@bradfitz
Copy link
Contributor

I'm not entirely convinced that the processes are too different. We review many documentation, tour, and example CLs today that have little or no code in them.

Is the proposal that they should be different and we should have some easier process for non-code contributions? If so, what? We already accept GitHub PRs these days at least, which made the process more familiar to a much larger audience.

Or is the proposal to add a grammar/English style guide? That would also be nice.

@bradfitz
Copy link
Contributor

I sent a CL to change "Contributing code" to "Contributing code and documentation" though.

@gopherbot
Copy link

Change https://golang.org/cl/202823 mentions this issue: doc: clarify that contributing isn't just for code

gopherbot pushed a commit that referenced this issue Oct 23, 2019
Updates #33323

Change-Id: I4b3076469f3db8ab0fe888edcf0471f17dc199e6
Reviewed-on: https://go-review.googlesource.com/c/go/+/202823
Reviewed-by: Robert Griesemer <gri@golang.org>
@rsc
Copy link
Contributor

rsc commented Oct 30, 2019

I'm not 100% sure what this issue means to be about.
If the claim is that there should be a different process for documentation vs code, that's not our intent. We intend to use the same review for everything, as Brad documented in CL 202823.
(That is, we're not going to add a separate process specific to documentation or examples.)

Are there other concrete changes we should make for this issue, or should we close it now?

Will leave open for a week for final comments and otherwise close as done.

@rsc
Copy link
Contributor

rsc commented Nov 6, 2019

Closing as done.

@rsc rsc closed this as completed Nov 6, 2019
@nathany
Copy link
Contributor Author

nathany commented Nov 6, 2019

Thanks

@golang golang locked and limited conversation to collaborators Nov 5, 2020
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

5 participants