Update Documentation Style Guide and .editorconfig

[nate-double-u]

This is a Feature Request

Following Geoffrey Cline's (@geoffcline) talk in last week's Kubernetes Contributor summit, "Linting English? Authoring docs in IDEs," we should update the Documentation Style Guide to mention the .editorconfig file and explain what it does. We should also ensure that the Style Guide and .editorconfig file match where the .editorconfig file overlaps the Style Guide.

What would you like to be added

1. Add a section to the Documentation Style Guide (https://kubernetes.io/docs/contribute/style/style-guide/) explaining the .editorconfig file and how to use it.

2. Ensure that the .editorconfig file and Documentation Style Guide match (where there is .editorconfig functionality to match).

Why is this needed

Where possible, we should make it easy to maintain consistent formatting and style, .editorconfig can help with this if it is well-understood and properly maintained.

Comments

EditorConfig website.

[divya-mohan0209]

/triage accepted

[sftim]

/priority backlog

[Karthik-PM]

/assign

[geoffcline]

Thanks for making this issue!

[a-mccarthy]

@Kart121 please reach out if you have any questions about this issue :)

@nate-double-u I think this is a great idea! Do we have any built in mechanisms we can use to make sure we continue to keep the .editconfig file updated when the style guide is updated?

[Karthik-PM]

@a-mccarthy yes! will do

[Karthik-PM]

@a-mccarthy is telling how to use .editorconfig necessary? cant we just add show how the config should look like and can direct to the editorconfig site for more information

[a-mccarthy]

@Karthik-PM Its likely not sustainable to keep directions of how to use the .editorconfig file for all the available editors. Many editors support editorconfig files be default if they exist in the folder. I think its enough to mention that this file is supported by default for many text editors and link to the editorconfig page for users to check if their editor is supported: https://editorconfig.org/#pre-installed

[nate-double-u]

@nate-double-u I think this is a great idea! Do we have any built in mechanisms we can use to make sure we continue to keep the .editconfig file updated when the style guide is updated?

I don't think there is any automated method -- we just need to review them every so often to make sure they haven't drifted apart.

[divya-mohan0209]

Hey @nate-double-u , given that we have documented the details around .editorconfig in our style guide, do you think there's anything else that's required to close this issue off? I see that there is a point #2 that states :

Ensure that the .editorconfig file and Documentation Style Guide match (where there is .editorconfig functionality to match).

Are there any ideas around how to do this? Or will this be a manual endeavour?

[nate-double-u]

Hi @divya-mohan0209, this would be a manual thing -- i don't think there is any automation that would help. This issue just highlights the need to check that we are making the correct suggestions in the .editorconfig file as it relates to the Style guide, and make updates if we aren't.