Merge pull request #4305 from mrbobbytables/update-comms-doc

Update communications guidelines

1 files changed, 71 insertions, 60 deletions

diff --git a/communication/README.md b/communication/README.md
index 784289c5..082be9ab 100644
--- a/communication/README.md
+++ b/communication/README.md
@@ -10,30 +10,31 @@ Here is an excerpt from the code of conduct:
 > requests, updating documentation, submitting pull requests or patches,
 > and other activities._
 
-## Purpose of this doc
+## Purpose of This Doc
 
 A detailed list of upstream communication platforms and resources for contributors.
 Since upstream contributors are generally consumers, many of our channels intertwine.
-See [Misc Community Resources] for more end user/troubleshooting targeted paths.
+See [Misc Community Resources](#misc-community-resources) for more end
+user/troubleshooting targeted paths.
 
 ## Community Groups
 
 Kubernetes encompasses many projects, organized into [community groups].
-The upstream communication flows through those channels, most
-notably in the Special Interest Groups [SIGs] that own the docs and
-codebases. Their communication channels may include mailing lists, slack channels,
-zoom meetings, meeting agenda/notes, and can be found on their READMEs and on the
-community groups/[SIGs] page.
+Upstream communication flows through those channels, most notably in the Special
+Interest Groups [SIGs] that own the docs and codebases. Their communication
+channels may include mailing lists, slack channels, zoom meetings, meeting
+agenda/notes, and can be found on their READMEs and on the community
+groups/[SIGs] page.
 
 You can actively or passively participate in one of the following ways:
-- the community groups public meeting(s) listed in the above community groups page
-- every Thursday at our [weekly community meeting] over [zoom] at [10am US Pacific Time]
-- intro sessions at KubeCon/CloudNativeCon live or recordings on YouTube[need a link here]
+- The community groups public meeting(s) listed in the above community groups page
+- Every Thursday at our [weekly community meeting] over [zoom] at [10am US Pacific Time]
+- Intro sessions at KubeCon/CloudNativeCon live or [recordings on YouTube]
 
-Nevertheless, below find a list of many general channels, groups
-and meetings devoted to the Kubernetes project. Please check the guidelines and
-any relevant chat/conversation history before posting. Spam and sales pitches are
-not tolerated on these platforms.
+Nevertheless, below find a list of many general channels, groups and meetings
+devoted to the Kubernetes project. Please check the guidelines and any relevant
+chat/conversation history before posting. Spam and sales pitches are not tolerated
+on these platforms.
 
 ## Decisions Are Made Here
 
@@ -41,7 +42,7 @@ The project is very large with a robust community group ecosystem and bubbling u
 information is important. Transparency is necessary and these channels are key:
 
 - [kubernetes-dev] mailing list - all upstream Kubernetes news and discussion.
-Many commmunity groups have charters that state they have to post here for
+Many community groups have charters that state they have to post here for
 certain topics like project wide changes. Joining this mailing list is required
 [k-dev moderators]
 for GitHub [org membership] and will get you access to all community docs that are
@@ -49,8 +50,9 @@ not in GitHub.
 - GitHub Issues and PRs in an [associated repository] and
 - KEPs[(Kubernetes Enhancement Proposals)]
   - We don't recommend following or watching any repository unless you are using
-  [heavy email filters]. Getting involved with the community group(s) directly is
-  the best way to find out how to best watch what you need on GitHub.  
+  [heavy email filters][best-practices]. Getting involved with the community
+  group(s) directly is the best way to find out how to best watch what you need
+  on GitHub.
 
 ## Discussions Happen Here
 
@@ -60,17 +62,19 @@ We talk a lot, too.
 
 Our real-time platform with Kubernetes enthusiasts spread across 250+ channels.
 Owned and operated by sig-contributor-experience.
-[Join] | [Slack Guidelines] | [slack moderators] | #kubernetes-dev
 
-Pro-tip: If you want to add a new channel, simply file a request following [these
-instructions].  
+[Join] | [Slack Guidelines] | [slack moderators] | [#kubernetes-dev]
+
+Pro-tip: If you want to add a new channel, simply file a request following
+[these instructions].
 
 ### Mailing lists and forums
 
-Most of the Kubernetes mailing lists are hosted through Google Groups or [Discuss Kubernetes].
-These also power most of the access to our documentation and calendar items like
-SIG meetings.  
-[mailing list guidelines] | [email filtering tips]
+Most of the Kubernetes mailing lists are hosted through Google Groups or
+[Discuss Kubernetes]. These also power most of the access to our documentation
+and calendar items like SIG meetings.
+
+[mailing list guidelines] | [email filtering tips][best-practices]
 
 - [kubernetes-announce] broadcasts major project announcements such as releases
 and security issues
@@ -78,35 +82,36 @@ and security issues
 - [Discuss Kubernetes] is a forum where Kubernetes users trade notes with sections
 for contributors and all kinds of ecosystem related content
 - Additional Google groups exist and can be joined for discussion related to each
-community groups as noted above.  These are linked from the [SIG list](/sig-list.md).
+community groups as noted above.  These are linked from the [SIG list][SIGs].
 
 ### Calendar & Meetings
 
-We use Zoom for all of our community group meetings and contributor programs.  
+We use Zoom for all of our community group meetings and contributor programs. -
 [Zoom Guidelines]
 
 We keep a [shared calendar] with all of our community group meetings. If you'd
-like a contributor event published, please reach out to #sig-contribex on slack.  
+like a contributor event published, please reach out to [#sig-contribex] on slack.
 
 ### Social Media & Blogs
 
-**Twitter**  
-- [@kubernetesio]  
- - owned and operated by CNCF. Contact: social@cncf.io
-- [Last Week in Kubernetes Development]  
- - owned and operated by Josh Berkus
+#### Twitter
+
+- [@kubernetesio]
+   - owned and operated by CNCF. Contact: social@cncf.io
+- [Last Week in Kubernetes Development]
+   - owned and operated by [Josh Berkus]
+
+#### YouTube
+
+Owned and operated by sig-contribex [community management] subproject.
+[Kubernetes Community channel] - recordings of community group meetings, Thursday
+community call, meet our contributors, office hours, and more [YouTube Guidelines].
+
+#### Kubernetes Blog
 
-**YouTube**   
-owned and operated by sig-contribex [community management] subproject  
-[Kubernetes Community channel] - recordings of
-community group meetings, Thursday community call, meet our contributors, office
-hours, and more  
-[YouTube Guidelines]  
+The [Kubernetes Blog] is owned by sig-docs and operated by the [blog team].
 
-**Kubernetes [Blog]**   
-owned by sig-docs and operated by the
-[blog team]  
-| [submit a blog post]| [2018 blog metrics]
+[submit a blog post] | [2018 blog metrics]
 
 ## Misc Community Resources
 ### Issues & Troubleshooting
@@ -117,8 +122,8 @@ try to post on discuss.kubernetes.io or if you think you found a bug, please [fi
 
 ### Office Hours
 
-Office hours are held once a month. Please refer to [the docs]()
-to learn more. Join the conversation on slack under #office-hours.
+Office hours are held once a month. Please refer to [the docs][office-hours]
+to learn more. Join the conversation on slack under [#office-hours].
 
 ### Other
 - [r/kubernetes] - reddit channel owned and operated by community members and
@@ -136,7 +141,7 @@ CNCF is the main driver for all KubeCon + CloudNativeCons, Kubernetes Forums,
 and the [Kubernetes Meetup Pro] program on meetup.com. KubeCon + CloudNativeCon,
 held every spring in Europe, summer in China, and winter in North America.
 Information about these and other community events is available on the CNCF [events]
-pages.  
+pages.
 
 The project also has several face to face meetings and contributor summits
 throughout the year. To stay updated, check the calendar, your community group of
@@ -151,7 +156,7 @@ place!
 
 
 
-[Blog]: https://kubernetes.io/blog/
+[Kubernetes Blog]: https://kubernetes.io/blog/
 [shared calendar]: https://calendar.google.com/calendar/embed?src=cgnt364vd8s86hr2phapfjc6uk%40group.calendar.google.com&ctz=America/Los_Angeles
 [Kubernetes code of conduct]: /code-of-conduct.md
 [events]: https://www.cncf.io/events/
@@ -164,30 +169,36 @@ place!
 [10am US Pacific Time]: https://www.google.com/search?q=1000+am+in+pst
 [troubleshooting guide]: https://kubernetes.io/docs/tasks/debug-application-cluster/troubleshooting/
 [@kubernetesio]: https://twitter.com/kubernetesio
+[Josh Berkus]: https://github.com/jberkus
 [zoom]: https://zoom.us/my/kubernetescommunity
+[k-dev moderators]: ./moderators.md#kubernetes-dev
 [weekly community meeting]: https://docs.google.com/document/d/1VQDIAB0OqiSjIHI8AWMvSdceWhnz56jNpZrLs6o7NJY/edit#
-[community groups]: https://git.k8s.io/community/governance.md#community-groups
+[recordings on YouTube]: https://www.youtube.com/channel/UCvqbFHwN-nwalWPjPUKpvTA
+[community groups]: /governance.md#community-groups
 [these instructions]: /slack-guidelines.md#requesting-a-channel
-[community management]: https://github.com/kubernetes/community/tree/master/sig-contributor-experience#community-management
+[community management]: /sig-contributor-experience#community-management
 [kubeweekly]: https://kubeweekly.io/
+[the docs]: /events/office-hours.md
 [r/kubernetes]: https://www.reddit.com/r/kubernetes/
 [awesome kubernetes list]: https://github.com/ramitsurana/awesome-kubernetes
 [Last Week in Kubernetes Development]: http://lwkd.info/
 [Kubernetes Meetup Pro]: https://github.com/cncf/meetups
-[associated repository]: https://github.com/kubernetes/community/tree/master/github-management#actively-used-github-organizations
-[Misc Community Resources]: #linktothissectionofdoc
-[mailing list guidelines]: https://git.k8s.io/community/communication/mailing-list-guidelines.md
+[associated repository]: /github-management#actively-used-github-organizations
+[mailing list guidelines]: ./mailing-list-guidelines.md
 [SIGs]: /sig-list.md
-[(Kubernetes Enhancement Proposals)]: https://github.com/kubernetes/enhancements/tree/master/keps
+[(Kubernetes Enhancement Proposals)]: https://git.k8s.io/enhancements/keps
 [Kubernetes Community channel]: https://www.youtube.com/c/kubernetescommunity
-[YouTube Guidelines]: https://github.com/kubernetes/community/blob/master/communication/youtube/youtube-guidelines.md
+[YouTube Guidelines]: ./youtube/youtube-guidelines.md
 [2018 blog metrics]: https://docs.google.com/spreadsheets/d/19nhQppxmFfrqoYue4JsxUKN6nTZ-ZOebjXOspumXjIc/edit?usp=sharing
-[email filtering tips]: https://github.com/kubernetes/community/blob/master/communication/best-practices.md
-[heavy email filters]: https://github.com/kubernetes/community/blob/master/communication/best-practices.md
-[org membership]: https://github.com/kubernetes/community/blob/master/community-membership.md
-[blog team]: https://github.com/kubernetes/community/tree/master/sig-docs/blog-subproject
+[best-practices]: ./best-practices.md
+[org membership]: /community-membership.md
+[blog team]: /sig-docs/blog-subproject
 [submit a blog post]: https://kubernetes.io/docs/contribute/start/#write-a-blog-post
-[zoom guidelines]: https://github.com/kubernetes/community/blob/master/communication/zoom-guidelines.md
+[zoom guidelines]: ./zoom-guidelines.md
 [the doc]: /events/office-hours.md
-[moderators]: https://github.com/kubernetes/community/blob/master/communication/moderators.md
-[slack moderators]: https://github.com/kubernetes/community/blob/master/communication/moderators.md#slack
+[moderators]: ./moderators.md
+[slack moderators]: ./moderators.md#slack
+[#kubernetes-dev]: https://app.slack.com/client/T09NY5SBT/C09R23FHP
+[#sig-contribex]: https://app.slack.com/client/T09NY5SBT/C1TU9EB9S
+[#office-hours]: https://app.slack.com/client/T09NY5SBT/C6RFQ3T5H
+[office hours]: /events/office-hours.md