From 43b2cd0905b85cbde7eb6caeb07b376957455414 Mon Sep 17 00:00:00 2001 From: kschueths <101272154+kschueths@users.noreply.github.com> Date: Tue, 12 Sep 2023 10:56:04 -0500 Subject: [PATCH 01/10] Update base-documentation.md Added COMMUNICATION.md and ADI instance --- .../project-setup/base-documentation.md | 29 ++++++++++++++++--- 1 file changed, 25 insertions(+), 4 deletions(-) diff --git a/patterns/2-structured/project-setup/base-documentation.md b/patterns/2-structured/project-setup/base-documentation.md index 7c726f0b7..0f4af50e4 100644 --- a/patterns/2-structured/project-setup/base-documentation.md +++ b/patterns/2-structured/project-setup/base-documentation.md @@ -6,7 +6,7 @@ Standard Base Documentation New contributors to an InnerSource project have a hard time figuring out who maintains the project, what to work on, and how to contribute. Providing -documentation in standard files like `README.md`/`CONTRIBUTING.md` enables a +documentation in standard files like `README.md`/`CONTRIBUTING.md`/`COMMUNICATION.md` enables a self service process for new contributors, so that they can find the answers to the most common questions on their own. @@ -81,6 +81,25 @@ topics: ![CONTRIBUTING.md](../../../assets/img/standard-base-documentation/CONTRIBUTING-for-contributors.png) +### COMMUNICATION.md + +Create a separate `COMMUNICATION.md` document. Link this document to your README.md so comprehensive contact information can be provided and not take up the extra space in your README. This document should answer frequently +asked questions about communicating with your team that contributors need to know. The goal is to streamline communications so users and contributors reach out to the correct person through a single channel. This reduces unnecessary distractions for team members and organizes communications so they do not get lost. + +These communications can be broken into ingoing and outgoing communications. Sections in the COMMUNICATION.md include: +Points of contact for incoming communication and how to contact those users. Some examples include: +* Reporting a bug +* Following up on a PR +* Feature requests +* Questions about documentation +* Escalations + +How and when the team communicates outbound with users and how to get added to those communications. Some examples include where/how to get communications about: +* Planned and unplanned outages +* Feature releases +* Code freezes +* Breaking changes + There are many of good examples for how to write a `README.md` and what kind of information to include in a `CONTRIBUTING.md` file in various open source projects. Pages like [how to write a readme that rocks](https://m.dotdev.co/how-to-write-a-readme-that-rocks-bc29f279611a), @@ -95,9 +114,9 @@ users and contributors will need. InnerSource projects likely will not cover all of those aspects right from the start, the list itself is helpful for inspiration for what one could cover. -In addition to that, this pattern comes with two very basic templates to get you -started right away: [README-template.md](templates/README-template.md) and -[CONTRIBUTING-template.md](templates/CONTRIBUTING-template.md) +In addition to that, this pattern comes with three very basic templates to get you +started right away: [README-template.md](templates/README-template.md), +[CONTRIBUTING-template.md](templates/CONTRIBUTING-template.md), and [COMMUNICATION-template.md](templates/COMMUNICATION-template.md). ## Resulting Context @@ -110,10 +129,12 @@ started right away: [README-template.md](templates/README-template.md) and * Europace AG - See blog post [InnerSource: Adding base documentation](https://tech.europace.de/post/innersource-base-documentation/) * Paypal Inc. * Mercado Libre - create a documentation site that contains how to get started with InnerSource and also define the basic artifacts that a repository must have to be InnerSource (README, CONTRIBUTING, CODING_GUIDELINES, etc). +* Analog Devices Inc. ## Authors * Isabel Drost-Fromm +* Katie Schueths ## Alias From 11009d41f7a9a0b1e0d5f637eda69915da5df592 Mon Sep 17 00:00:00 2001 From: Sebastian Spier Date: Tue, 12 Sep 2023 20:10:11 +0200 Subject: [PATCH 02/10] Fix linter issues --- patterns/2-structured/project-setup/base-documentation.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/patterns/2-structured/project-setup/base-documentation.md b/patterns/2-structured/project-setup/base-documentation.md index 0f4af50e4..81e82cf5d 100644 --- a/patterns/2-structured/project-setup/base-documentation.md +++ b/patterns/2-structured/project-setup/base-documentation.md @@ -88,6 +88,7 @@ asked questions about communicating with your team that contributors need to kno These communications can be broken into ingoing and outgoing communications. Sections in the COMMUNICATION.md include: Points of contact for incoming communication and how to contact those users. Some examples include: + * Reporting a bug * Following up on a PR * Feature requests @@ -95,6 +96,7 @@ Points of contact for incoming communication and how to contact those users. Som * Escalations How and when the team communicates outbound with users and how to get added to those communications. Some examples include where/how to get communications about: + * Planned and unplanned outages * Feature releases * Code freezes @@ -115,7 +117,7 @@ of those aspects right from the start, the list itself is helpful for inspiration for what one could cover. In addition to that, this pattern comes with three very basic templates to get you -started right away: [README-template.md](templates/README-template.md), +started right away: [README-template.md](templates/README-template.md), [CONTRIBUTING-template.md](templates/CONTRIBUTING-template.md), and [COMMUNICATION-template.md](templates/COMMUNICATION-template.md). ## Resulting Context From 2c3e717a1b3a5bc7cb183780f4f1677dadab2cd7 Mon Sep 17 00:00:00 2001 From: Sebastian Spier Date: Tue, 12 Sep 2023 20:10:41 +0200 Subject: [PATCH 03/10] Fix (potential) rendering issue in gitbook --- patterns/2-structured/project-setup/base-documentation.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/patterns/2-structured/project-setup/base-documentation.md b/patterns/2-structured/project-setup/base-documentation.md index 81e82cf5d..e64261007 100644 --- a/patterns/2-structured/project-setup/base-documentation.md +++ b/patterns/2-structured/project-setup/base-documentation.md @@ -109,8 +109,7 @@ Pages like [how to write a readme that rocks](https://m.dotdev.co/how-to-write-a the book [Producing Open Source](https://producingoss.com/en/producingoss.html) all have valuable information on what kind of information to provide. While Producing Open Source does not have a chapter on writing a good README per se, -the [Getting Started -chapter](https://producingoss.com/en/producingoss.html#starting-from-what-you-have) +the [Getting Started chapter](https://producingoss.com/en/producingoss.html#starting-from-what-you-have) does provide a fairly extensive list of things that fellow host team members, users and contributors will need. InnerSource projects likely will not cover all of those aspects right from the start, the list itself is helpful for From 7f361c126e40909a82ea94440ca9c6414bce1d2c Mon Sep 17 00:00:00 2001 From: Sebastian Spier Date: Tue, 12 Sep 2023 20:12:02 +0200 Subject: [PATCH 04/10] [vale] 'incoming' seems like a reasonable replacement? --- patterns/2-structured/project-setup/base-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/patterns/2-structured/project-setup/base-documentation.md b/patterns/2-structured/project-setup/base-documentation.md index e64261007..07376584e 100644 --- a/patterns/2-structured/project-setup/base-documentation.md +++ b/patterns/2-structured/project-setup/base-documentation.md @@ -86,7 +86,7 @@ topics: Create a separate `COMMUNICATION.md` document. Link this document to your README.md so comprehensive contact information can be provided and not take up the extra space in your README. This document should answer frequently asked questions about communicating with your team that contributors need to know. The goal is to streamline communications so users and contributors reach out to the correct person through a single channel. This reduces unnecessary distractions for team members and organizes communications so they do not get lost. -These communications can be broken into ingoing and outgoing communications. Sections in the COMMUNICATION.md include: +These communications can be broken into incoming and outgoing communications. Sections in the COMMUNICATION.md include: Points of contact for incoming communication and how to contact those users. Some examples include: * Reporting a bug From 2b248015c491fceb554e17d8456338b863845446 Mon Sep 17 00:00:00 2001 From: Sebastian Spier Date: Tue, 12 Sep 2023 21:00:38 +0200 Subject: [PATCH 05/10] Formatting --- patterns/2-structured/project-setup/base-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/patterns/2-structured/project-setup/base-documentation.md b/patterns/2-structured/project-setup/base-documentation.md index 07376584e..edf81581d 100644 --- a/patterns/2-structured/project-setup/base-documentation.md +++ b/patterns/2-structured/project-setup/base-documentation.md @@ -83,7 +83,7 @@ topics: ### COMMUNICATION.md -Create a separate `COMMUNICATION.md` document. Link this document to your README.md so comprehensive contact information can be provided and not take up the extra space in your README. This document should answer frequently +Create a separate `COMMUNICATION.md` document. Link this document to your `README.md` so comprehensive contact information can be provided and not take up the extra space in your README. This document should answer frequently asked questions about communicating with your team that contributors need to know. The goal is to streamline communications so users and contributors reach out to the correct person through a single channel. This reduces unnecessary distractions for team members and organizes communications so they do not get lost. These communications can be broken into incoming and outgoing communications. Sections in the COMMUNICATION.md include: From 2eefd4b4f2c2c64696463e721bb22aa3ede6738d Mon Sep 17 00:00:00 2001 From: Sebastian Spier Date: Tue, 12 Sep 2023 21:06:11 +0200 Subject: [PATCH 06/10] Adding COMMUNICATION template to the sidebar of the book (en only)0 --- book/en/toc_template.md | 1 + 1 file changed, 1 insertion(+) diff --git a/book/en/toc_template.md b/book/en/toc_template.md index ab97fe117..cb7b3b956 100644 --- a/book/en/toc_template.md +++ b/book/en/toc_template.md @@ -27,6 +27,7 @@ Instead edit toc_template.md * Extras * [README Template](../../patterns/2-structured/project-setup/templates/README-template.md) * [CONTRIBUTING Template](../../patterns/2-structured/project-setup/templates/CONTRIBUTING-template.md) + * [COMMUNICATION Template](../../patterns/2-structured/project-setup/templates/COMMUNICATION-template.md) * [RFC Template](../../patterns/2-structured/templates/rfc.md) ## Resources From 40b2a227c2098718d6c20790b9c3848e37bcfddb Mon Sep 17 00:00:00 2001 From: Sebastian Spier Date: Tue, 12 Sep 2023 21:07:28 +0200 Subject: [PATCH 07/10] Spotting up Authors and Acknowledgements --- patterns/2-structured/project-setup/base-documentation.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/patterns/2-structured/project-setup/base-documentation.md b/patterns/2-structured/project-setup/base-documentation.md index edf81581d..9c5c20982 100644 --- a/patterns/2-structured/project-setup/base-documentation.md +++ b/patterns/2-structured/project-setup/base-documentation.md @@ -135,7 +135,10 @@ started right away: [README-template.md](templates/README-template.md), ## Authors * Isabel Drost-Fromm -* Katie Schueths + +## Acknowledgments + +* Katie Schueths - for adding the `COMMUNICATION.md` concept ## Alias From 83b7bedf7291f3a1657c6bf212bc4d51155f10a4 Mon Sep 17 00:00:00 2001 From: kschueths <101272154+kschueths@users.noreply.github.com> Date: Wed, 13 Sep 2023 11:33:42 -0500 Subject: [PATCH 08/10] Update base-documentation.md --- patterns/2-structured/project-setup/base-documentation.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/patterns/2-structured/project-setup/base-documentation.md b/patterns/2-structured/project-setup/base-documentation.md index 9c5c20982..ecdd48a9e 100644 --- a/patterns/2-structured/project-setup/base-documentation.md +++ b/patterns/2-structured/project-setup/base-documentation.md @@ -86,8 +86,9 @@ topics: Create a separate `COMMUNICATION.md` document. Link this document to your `README.md` so comprehensive contact information can be provided and not take up the extra space in your README. This document should answer frequently asked questions about communicating with your team that contributors need to know. The goal is to streamline communications so users and contributors reach out to the correct person through a single channel. This reduces unnecessary distractions for team members and organizes communications so they do not get lost. -These communications can be broken into incoming and outgoing communications. Sections in the COMMUNICATION.md include: -Points of contact for incoming communication and how to contact those users. Some examples include: +Sections in the COMMUNICATION.md points of contact for incoming communications and information about outgoing communications from the project's ownership team. Included below are some examples. + +Points of contact for incoming communication and how to contact those users: * Reporting a bug * Following up on a PR @@ -95,7 +96,7 @@ Points of contact for incoming communication and how to contact those users. Som * Questions about documentation * Escalations -How and when the team communicates outbound with users and how to get added to those communications. Some examples include where/how to get communications about: +How and when the team communicates outbound with users and how to get added to those communications: * Planned and unplanned outages * Feature releases From 997d7eee06697408076a4b9887c11a08cd7361f4 Mon Sep 17 00:00:00 2001 From: Sebastian Spier Date: Wed, 13 Sep 2023 19:24:57 +0200 Subject: [PATCH 09/10] Formatting --- patterns/2-structured/project-setup/base-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/patterns/2-structured/project-setup/base-documentation.md b/patterns/2-structured/project-setup/base-documentation.md index ecdd48a9e..b6891cca0 100644 --- a/patterns/2-structured/project-setup/base-documentation.md +++ b/patterns/2-structured/project-setup/base-documentation.md @@ -86,7 +86,7 @@ topics: Create a separate `COMMUNICATION.md` document. Link this document to your `README.md` so comprehensive contact information can be provided and not take up the extra space in your README. This document should answer frequently asked questions about communicating with your team that contributors need to know. The goal is to streamline communications so users and contributors reach out to the correct person through a single channel. This reduces unnecessary distractions for team members and organizes communications so they do not get lost. -Sections in the COMMUNICATION.md points of contact for incoming communications and information about outgoing communications from the project's ownership team. Included below are some examples. +Sections in the `COMMUNICATION.md` points of contact for incoming communications and information about outgoing communications from the project's ownership team. Included below are some examples. Points of contact for incoming communication and how to contact those users: From 746e6105dd7554eff15d143740a3cfbfe94ac382 Mon Sep 17 00:00:00 2001 From: Sebastian Spier Date: Thu, 14 Sep 2023 21:31:45 +0200 Subject: [PATCH 10/10] Wording fix. --- patterns/2-structured/project-setup/base-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/patterns/2-structured/project-setup/base-documentation.md b/patterns/2-structured/project-setup/base-documentation.md index b6891cca0..8e6ebc538 100644 --- a/patterns/2-structured/project-setup/base-documentation.md +++ b/patterns/2-structured/project-setup/base-documentation.md @@ -86,7 +86,7 @@ topics: Create a separate `COMMUNICATION.md` document. Link this document to your `README.md` so comprehensive contact information can be provided and not take up the extra space in your README. This document should answer frequently asked questions about communicating with your team that contributors need to know. The goal is to streamline communications so users and contributors reach out to the correct person through a single channel. This reduces unnecessary distractions for team members and organizes communications so they do not get lost. -Sections in the `COMMUNICATION.md` points of contact for incoming communications and information about outgoing communications from the project's ownership team. Included below are some examples. +Sections in the `COMMUNICATION.md` include points of contact for incoming communications and information about outgoing communications from the project's ownership team. See some examples below. Points of contact for incoming communication and how to contact those users: