-
Notifications
You must be signed in to change notification settings - Fork 201
Standard Base Documentation: COMMUNICATION.md vs SUPPORT.md #665
-
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:
image
References:
Beta Was this translation helpful? Give feedback.
All reactions
-
👀 1
Replies: 2 comments 5 replies
-
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?
Beta Was this translation helpful? Give feedback.
All reactions
-
@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?
Beta Was this translation helpful? Give feedback.
All reactions
-
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
.
Beta Was this translation helpful? Give feedback.
All reactions
-
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.
Beta Was this translation helpful? Give feedback.
All reactions
-
👍 1
-
It would be good to also "standardize" the README sections, to facilitate "linting" the repositories with rules that check for adoption of this pattern.
Beta Was this translation helpful? Give feedback.
All reactions
-
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.
Beta Was this translation helpful? Give feedback.
All reactions
-
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.
Beta Was this translation helpful? Give feedback.