Improve 'Communication Tooling' pattern

[spier]

While reading the fantastic Communication Tooling pattern I noticed some areas that I could improve.

So I took the opportunity to do this, while also allowing me to ask inline questions about this pattern as part of this PR.

Quick link to the modified pattern:
communication-tooling.md

Key changes

• Changing order of sections according to pattern template
• Changing the Patlet to a more clear Problem/Solution split.
• More clearly call out the different types of communication channels.
• Add links to related patterns
• Extend section on channeling comms back to the main 3 channels
• Add a visual. Maybe a picture that describes how a user decides which comms channel to use?
• Look for another org that can confirm a Known Instance on this (in preparation for leveling this pattern up to "Validated")

[spier]

I am toying around with a visual to support this pattern. So far I got this:

Another visual idea is to to show requests dropping from the top into some sort of funnel, and then the funnel guides the requests to the correct communication tool. With this I would like to show how the project team (and users) make the decision about which tool/channel to use for what.

I am happy to share the source for this visual above if anybody wants to help.

[NewMexicoKid]

I am toying around with a visual to support this pattern

I was curious whether the private channels would also include trusted committers? So a subset of the downstream users might have access to the private channels.

[spier]

I was curious whether the private channels would also include trusted committers? So a subset of the downstream users might have access to the private channels.

Based on the text it seems like it would.
In that case we should add "host team + trusted committers" under the person on the left in the visual.
I want to make it clear that not all users use all of these channels and that the way they use them might also differ.

Could also be that a completely different visualization would actually be more helpful :)

[NewMexicoKid]

I might put the trusted committers as a second person on the right as they are usually a small subset of the users and usually are not a part of the host team (except in a functional/trust sense).

…

On Fri, May 27, 2022 at 9:22 AM Sebastian Spier ***@***.***> wrote: I was curious whether the private channels would also include trusted committers? So a subset of the downstream users might have access to the private channels. Based on the text it seems like it would. In that case we should add "host team + trusted committers" under the person on the left in the visual. I want to make it clear that not all users use all of these channels and that they way they use them might also differ. Could also be that a completely different visualization would actually be more helpful :) — Reply to this email directly, view it on GitHub <#420 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AARUJ4D2ZKYRCD7ZBGDNJ2LVMDLCHANCNFSM5XAXAIAA> . You are receiving this because your review was requested.Message ID: ***@***.***>

-- Tim Yao - ***@***.*** ***@***.***> ***@***.***> aka NewMexicoKid at National Novel Writing Month, http://nanowrimo.org <http://www.nanowrimo.org> co-Municipal Liaison for the Illinois::Naperville region NaperWriMo - http://naperwrimo.org

[spier]

I might put the trusted committers as a second person on the right as they are usually a small subset of the users and usually are not a part of the host team (except in a functional/trust sense).

Right, that is also an option.
However if the TCs have the same access to the Communication channels as the people in the host team, then the visual starts to be confusing.

I did some other fixes and this is the latest version of the visual:

[spier]

@MaineC it would be great to get a review from you on this PR, which I think contains some improvements to this pattern.
Also note that the visual in the comment thread above has not been included in the pattern yet, as I wanted to see first if people even like it at all.

[ranton256]

One other suggested improvement is to clarify the statement "All communication channels should be documented in the project README.md." in the current pattern.
I think giving users some guidance which channels to prefer/when for what types of questions is helpful to collaborators and users when more than one channel is available.

[spier]

One other suggested improvement is to clarify the statement "All communication channels should be documented in the project README.md." in the current pattern.
I think giving users some guidance which channels to prefer/when for what types of questions is helpful to collaborators and users when more than one channel is available.

Good point @ranton256.

I could imagine that we might add a little "mock snippet" of how the description of the communication channels in the README.md could look like. Then people can copy that and adapt it for the needs of their project.

[spier]

I was just wondering:
Most projects will want to use, or even have to use, the tools that their org already provides. e.g. if the org is using JIRA as an issue tracker, they might have to use that for their project too.

Should we call this out in this pattern as well?
i.e. not surprizing users by the choice of communication channels should be considered a plus in the InnerSource context?

[spier]

While this PR received some favorable comments, it did not receive a full review yet.

I am trying to push the updates to this pattern to our book now, as the pattern was just shared in the March 2023 ISC newsletter, so I am hoping that it might get some more eyeballs than it normally would.

@robtuley @yuhattor @NewMexicoKid would one of you be able to review (and possibly approve) this PR, so that we can put this live?

[robtuley]

🚀 These all look like good quality improvements to me.

[robtuley]

Look for another org that can confirm a Known Instance on this (in preparation for leveling this pattern up to "Validated")

If you're still looking for another which is the remaining un-checked task you can also add "Flutter Entertainment" to the list here. We use Slack a lot, but this pattern closely resembles internal guidance on this topic. I can't share the full page as it has private references but this is a publically safe snippet from the top as an example:

[spier]

Thanks for your review @robtuley. Much appreciated.
This is live now at:
https://patterns.innersourcecommons.org/p/communication-tooling

As for adding a known instance:
That would be awesome! Would you mind doing that via a new PR, so that we have a better trace of that activity?

Personally I am curious if Flutter Entertainment uses the same types of channels that are called out in this pattern?

Also if you made any other experiences specific to this approach e.g. do you have to explain the communication channels and their purpose only in a single place (your screenshot looks like that), or do teams also add specifics about their use of these channels to their projects?