Facilitate Communication with a COMMUNICATION.MD Document

[kschueths]

This is a rough pattern that is in the works. I am working on a pattern for the COMMUNICATION.MD template attached to this issue.

Facilitate Communication with a COMMUNICATION.MD Document

COMMUNICATION.MD template

Patlet / Summary

Concise 1-2 sentence description of the problem and solution.

Problem

What is the problem - crisp definition of the problem.
Short description, usually not more than a couple sentences, that describes what the issues and challenges are.
Be careful not to morph into information found in other sections below.

Context

Where does the problem exist?
What are the pre-conditions?
Unchangeable before the solution goes into place.
The content here is often tied to the applicability of the pattern for other readers: "Do I have this same particular situation?"

Forces

What makes the problem difficult?
What are the trade-offs?
These are constraints that can be changed at a cost.
The solution might change one or more of these forces in order to solve the problem, while also in-turn changing the context.

Solutions

Verified resolutions and possible resolutions to the problem.

Resulting Context

What is the situation after the problem has been solved?
The original context is changed indirectly by way of the solution.
Often this section can include discussion of the next possible Patterns/problems introduced.
This section can be short in content - the solution may not introduce new problems or change much context.

Known Instances

Indeed.com

May mention:

• A particular business
• Anonymized instances ex: "3 companies have proven that this is a good solution" or "A large financial services org...".

Status

Rough draft
Communication Process Template.pdf

Initial

Author(s) (optional)

Katie Schueths
Often, this is yourself.

[spier]

Thanks for sharing this @kschueths. Also great to see that you found and used the issue template :)

Curious to see how your new pattern here relates to Communication Tooling.

Aside:
We should probably try to hide the instructions text once the issue is submitted. We could possibly wrap those in HTML quotes like <!-- instructions -->. I think I have seen that being used elsewhere.

[spier]

Hi @kschueths. Thanks again for sharing this content.

I was wondering if you have additional information to share about this approach, and would like to take this forward in the form of a pattern?
Also if you have seen this approach documented elsewhere, links to those resources would be super helpful.

Thanks again for contributing to our patterns!

[kschueths]

@spier I was laid off at Indeed in the big layoff. I will be starting at Analog Devices in late June. Once I am there I plan on working on this again. I put this up in a rush the day before I left Indeed to make sure it was in public domain and Indeed could be used as an instance (I had permission to put it up). I am taking a work hiatus until then and just being periphery to the external groups I am part of. Once I start the program at ADI, they will also become a known instance.

[spier]

Sounds great! Enjoy your break! :)

[spier]

When discussing this pattern idea with @kschueths the other day, we thought that this would naturally fit into the Standard Base Documentation pattern.

Also see an example template for a COMMUNICATION.md here.

By doing so we might also be able to add further Known Instances to that pattern, as @kschueths mentioned that this is used at various orgs that she knows about.

Some thoughts on adding this new COMMUNICATION.md standard file to the pattern:

• it is key to describe what exact problem that file is solving.
• worth checking if teams may also opt to merge the content intended for COMMUNICATION.md into README.md as that file is often rendered first by the VCS (assuming that this information should be one of the first things that the users see)
• is a similar approach used in open source? (asking this because README.md/CONTRIBUTING.md are standard in open source too)

And possibly even if there are any anti-patterns to watch out for. e.g. I could imagine that an org would want to use many of their teams to use the exact same tool for issue tracking (bug reports + features). Therefore the information that the team fills in COMMUNICATION.md should be as unsurprizing as possible for the users.

Lastly there is a possible overlap with another pattern: Communication Tooling. Worth checking at least if we should somehow link from one pattern to the other.

[spier]

@kschueths should we start by adding the most simple extension to the Standard Base Documentation, related to COMMUNICATION.md? That way we would at least be able to link to the template file that you created, so that it is more likely that others can find it.

My last comment above mentions a couple of further ideas but maybe we should start with the most basic?

[spier]

Implemented through #589