The docs should prefer `.yaml` over `.yml`

[Jayman2000]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

This is an improvement that could be made throughout the documentation.

What part(s) of the article would you like to see updated?

According to the IANA Media Types list, “yaml” is the preferred file extension for YAML files. “yml” is still a valid file extension, but it’s not preferred. At the moment, it looks like GitHub’s docs use .yml much more often than they use .yaml:

$ cd docs/
$ git grep --fixed-strings .yaml | wc --lines
543
$ git grep --fixed-strings .yml | wc --lines
1328
$ 

There probably are sometimes where using .yml works and using .yaml doesn’t work, but I have a feeling that most of the time the docs could use .yaml instead of .yml. Here’s an example that demonstrates why I think that way:

$ cd docs/
$ git grep --fixed-strings dependabot.yaml | wc --lines
0
$ git grep --fixed-strings dependabot.yml | wc --lines
144
$ 

The docs never mention dependabot.yaml even though dependabot itself supports dependabot.yaml.

---

I think that it would be better if the docs almost always used .yaml and only used .yml when using it is necessary or when describing that <whatever>.yml can be used instead of <whatever>.yaml.

Additional information

No response

[welcome]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[Sharra-writes]

@Jayman2000 Thanks for opening an issue! I talked to our engineers, and they say retroactively changing things might not be a problem, but they're worried about unforeseen consequences. I would have to check in with every stakeholder on every product described in the docs to find out whether it would create issues in their code. That's an unreasonable amount of work for that change, and it's not something an open source contributor could take on. I'm afraid the scope is just too massive, and not a priority for the docs team as a whole.

I'm sorry that it's not something we have the resources for. I wish I had a different/better answer for you. If you see another issue in the docs you think warrants a look, please feel free to bring it up.