Skip to content

Commit c6670ce

Browse files
authoredSep 14, 2023
Adding the COMMUNICATION.md to the Standard Base Documentation pattern (InnerSourceCommons#589)
* Added COMMUNICATION.md and ADI instance to base-documentation.md. * Adding COMMUNICATION template to the sidebar of the book (en only)0
1 parent c6e300f commit c6670ce

File tree

2 files changed

+33
-6
lines changed

2 files changed

+33
-6
lines changed
 

‎book/en/toc_template.md

+1
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ Instead edit toc_template.md
2727
* Extras
2828
* [README Template](../../patterns/2-structured/project-setup/templates/README-template.md)
2929
* [CONTRIBUTING Template](../../patterns/2-structured/project-setup/templates/CONTRIBUTING-template.md)
30+
* [COMMUNICATION Template](../../patterns/2-structured/project-setup/templates/COMMUNICATION-template.md)
3031
* [RFC Template](../../patterns/2-structured/templates/rfc.md)
3132

3233
## Resources

‎patterns/2-structured/project-setup/base-documentation.md

+32-6
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Standard Base Documentation
66

77
New contributors to an InnerSource project have a hard time figuring out who
88
maintains the project, what to work on, and how to contribute. Providing
9-
documentation in standard files like `README.md`/`CONTRIBUTING.md` enables a
9+
documentation in standard files like `README.md`/`CONTRIBUTING.md`/`COMMUNICATION.md` enables a
1010
self service process for new contributors, so that they can find the answers to
1111
the most common questions on their own.
1212

@@ -81,23 +81,44 @@ topics:
8181

8282
![CONTRIBUTING.md](../../../assets/img/standard-base-documentation/CONTRIBUTING-for-contributors.png)
8383

84+
### COMMUNICATION.md
85+
86+
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
87+
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.
88+
89+
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.
90+
91+
Points of contact for incoming communication and how to contact those users:
92+
93+
* Reporting a bug
94+
* Following up on a PR
95+
* Feature requests
96+
* Questions about documentation
97+
* Escalations
98+
99+
How and when the team communicates outbound with users and how to get added to those communications:
100+
101+
* Planned and unplanned outages
102+
* Feature releases
103+
* Code freezes
104+
* Breaking changes
105+
84106
There are many of good examples for how to write a `README.md` and what kind
85107
of information to include in a `CONTRIBUTING.md` file in various open source projects.
86108
Pages like [how to write a readme that rocks](https://m.dotdev.co/how-to-write-a-readme-that-rocks-bc29f279611a),
87109
[Open Source Guide from GitHub](https://opensource.guide/) as well as
88110
the book [Producing Open Source](https://producingoss.com/en/producingoss.html)
89111
all have valuable information on what kind of information to provide. While
90112
Producing Open Source does not have a chapter on writing a good README per se,
91-
the [Getting Started
92-
chapter](https://producingoss.com/en/producingoss.html#starting-from-what-you-have)
113+
the [Getting Started chapter](https://producingoss.com/en/producingoss.html#starting-from-what-you-have)
93114
does provide a fairly extensive list of things that fellow host team members,
94115
users and contributors will need. InnerSource projects likely will not cover all
95116
of those aspects right from the start, the list itself is helpful for
96117
inspiration for what one could cover.
97118

98-
In addition to that, this pattern comes with two very basic templates to get you
99-
started right away: [README-template.md](templates/README-template.md) and
100-
[CONTRIBUTING-template.md](templates/CONTRIBUTING-template.md)
119+
In addition to that, this pattern comes with three very basic templates to get you
120+
started right away: [README-template.md](templates/README-template.md),
121+
[CONTRIBUTING-template.md](templates/CONTRIBUTING-template.md), and [COMMUNICATION-template.md](templates/COMMUNICATION-template.md).
101122

102123
## Resulting Context
103124

@@ -110,11 +131,16 @@ started right away: [README-template.md](templates/README-template.md) and
110131
* Europace AG - See blog post [InnerSource: Adding base documentation](https://tech.europace.de/post/innersource-base-documentation/)
111132
* Paypal Inc.
112133
* 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).
134+
* Analog Devices Inc.
113135

114136
## Authors
115137

116138
* Isabel Drost-Fromm
117139

140+
## Acknowledgments
141+
142+
* Katie Schueths - for adding the `COMMUNICATION.md` concept
143+
118144
## Alias
119145

120146
Provide standard base documentation through a README

0 commit comments

Comments
 (0)
Please sign in to comment.