Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Sign up
Appearance settings

Standard Base Documentation: COMMUNICATION.md vs SUPPORT.md #665

dellagustin-sap started this conversation in General
Discussion options

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:

You must be logged in to vote

Replies: 2 comments 5 replies

Comment options

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?

You must be logged in to vote
5 replies
Comment options

@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?

Comment options

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.

Comment options

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.

Comment options

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

Comment options

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.

Comment options

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.

You must be logged in to vote
0 replies
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet

AltStyle によって変換されたページ (->オリジナル) /