Skip to content
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

Adding the COMMUNICATION.md to the Standard Base Documentation pattern #589

Merged
merged 10 commits into from
Sep 14, 2023
Merged

Adding the COMMUNICATION.md to the Standard Base Documentation pattern #589

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
43b2cd0
Update base-documentation.md
kschueths Sep 12, 2023
11009d4
Fix linter issues
spier Sep 12, 2023
2c3e717
Fix (potential) rendering issue in gitbook
spier Sep 12, 2023
7f361c1
[vale] 'incoming' seems like a reasonable replacement?
spier Sep 12, 2023
2b24801
Formatting
spier Sep 12, 2023
2eefd4b
Adding COMMUNICATION template to the sidebar of the book (en only)0
spier Sep 12, 2023
40b2a22
Spotting up Authors and Acknowledgements
spier Sep 12, 2023
83b7bed
Update base-documentation.md
kschueths Sep 13, 2023
997d7ee
Formatting
spier Sep 13, 2023
746e610
Wording fix.
spier Sep 14, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions book/en/toc_template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
38 changes: 32 additions & 6 deletions patterns/2-structured/project-setup/base-documentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -81,23 +81,44 @@ 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.

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:

* 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:

* 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),
[Open Source Guide from GitHub](https://opensource.guide/) as well as
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
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

Expand All @@ -110,11 +131,16 @@ 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

## Acknowledgments

* Katie Schueths - for adding the `COMMUNICATION.md` concept

## Alias

Provide standard base documentation through a README
Expand Down