Standard Base Documentation: COMMUNICATION.md vs SUPPORT.md

[dellagustin-sap]

The Standard Base Documentation describes the COMMUNICATION.md file, which contains some overlaps with the well known SUPPORT.md file.

I'm starting this discussion to understand the reasoning behind not using SUPPORT.md (e.g. was it unknown, or was it a decision for not using it).

I could not find extensive documentation on how tools (e.g. GitHub) consume this files, but I know that GitHbu shows it on Helpful resources when you are creating an issue:

References:

• https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-support-resources-to-your-project
• https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file

[dellagustin-sap]

Hi @kschueths , as you contributed with COMMUNICATION.md, did you consider using SUPPORT.md?
Could you help us understand why one was chosen over the other?

[spier]

@dellagustin-sap interesting discussion!

A question out of curiosity:
Any hunch where the names of these files comes from? i.e. is this something that GitHub made up themselves, or does this have a longer history in open source? e.g. maybe there is even a RFC that suggests the use of certain file names.

Also, to clarify the improvement opportunity here:
If SUPPORT.md is indeed the better known file name for the kind of content that we now show under COMMUNICATION.md in our pattern, then it would make sense to rename this in our pattern as well, to reduce possible confusion of readers. Right?

[dellagustin-sap]

Any hunch where the names of these files comes from? i.e. is this something that GitHub made up themselves, or does this have a longer history in open source? e.g. maybe there is even a RFC that suggests the use of certain file names.

I first learned of them by using GitHub. I have searched a bit about it, but could not find traces of the origin of the practice.

While searching for it, I also saw that https://opensource.guide/best-practices/ recommends documenting the vision for the project on a VISION(.md) file, which I quite like.
I have done this in a the README.md section of my main open source project (https://github.com/podStation/podStation) long with a History section, which, if larger, could go into a HISTORY.md.

[spier]

It is kind of always the same idea with all of these files:

You can document it all in the README. If that grows too large, you can split it up.

Whether that split happens or not depends in parts on the personal preference of the maintainers.

[dellagustin-sap]

It would be good to also "standardize" the README sections, to facilitate "linting" the repositories with rules that check for adoption of this pattern.

[kschueths]

I don't believe support.md was on our radar when this was made. I am definitely open to changing it to standardize the document.

[spier]

FYI @dellagustin-sap I contacted @kschueths via slack as well, to see if we can add some more color to this conversation, and decide where we want to go with it.