Go: doc: tidy up contribute guide

[robpike]

See https://go-review.googlesource.com/c/go/+/93495

[mvdan]

@robpike is there a document that goes over these English writing techniques that I've seen you advocate for in reviews? I've caught onto the basics, such as keeping sentences simple and the oxford comma, but it would be great if there was a document somewhere.

Think of it as another "Effective Go" or "Go code review comments", but for writing documentation.

[dgryski]

I hope I'm not out of place to note that The Practice of Programming first chapter Supplementary Reading section recommends "The Elements of Style" by Strunk and White.

[robpike]

Writing good prose is a lifetime-long learning process. There is no simple set of rules that covers correctness, felicity, style, flow, consistency, clarity, ...

[pciet]

There are natural language rules that would be helpful for contributors, reviewers and most importantly for code and documentation readers. Here’s three proposals from me:

• Minimize things needed to understand. Don’t include cultural concepts like baseball terms or an experience that happens when driving a car. For example “this is a red flag” may be confusing in a Chinese context. Avoid i.e. and e.g.
• No mistakes caught by an American English spelling and grammar checker program or person.
• Any function or method signature should be narrowly self-documenting.

The idea of natural language forks is interesting to me and minimizing the English complexity would help multi-lingual people doing the conversion. Keeping in mind minimal complexity for Google Translate and competitors also may help people.

For contribution outside of the repository I think this is mentioned already in the code of conduct but to me it seems important:

• Understanding written language meaning and emotion is difficult, so don't make assumptions.

[ghost]

“this is a red flag” what did you mean in chinese? @pciet

[pciet]

@ctriple if my flag was mostly red like that of the People's Republic of China and I hadn't heard that term then I wouldn't necessarily expect it to mean something negative.

Reading Wikipedia apparently the term originates from sailing racing starting in the 1600s, but as somebody born in the late 1900s as a USA citizen I'm sensitive to possible Cold War connotation and don't want to send a history-insensitive message accidentally with locally acceptable language in an international context. "This is a red flag" is ambiguous.

[gopherbot]

Change https://golang.org/cl/113015 mentions this issue: doc/contribute.html: clean up HTML and formatting

[gopherbot]

Change https://golang.org/cl/113016 mentions this issue: doc/contribute.html: English cleanups