10000 proposal: create contribution guidelines for technical writers · Issue #33323 · golang/go · GitHub
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

proposal: create contribution guidelines for technical writers #33323

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.

Sign up for GitHub

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

Jump to bottom
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
Labels
FrozenDueToAge Proposal Proposal-FinalCommentPeriod
Milestone
Proposal

Comments

@nathany
Copy link
Contributor
nathany commented Jul 27, 2019 •
edited
Loading

(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.

@andybons andybons mentioned this issue Oct 9, 2019
Open
@nathany
Copy link
Contributor Author
nathany commented Oct 12, 2019 •
edited
Loading

"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
Contributor

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
@bradfitz
doc: clarify that contributing isn't just for code
7879064 
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.
Assignees
No one assigned
Labels
FrozenDueToAge Proposal Proposal-FinalCommentPeriod
Projects
None yet
Milestone
Proposal
Development

No branches or pull requests
5 participants
@bradfitz @nathany @rsc @mvdan @gopherbot
0