Add Style Guide

[iHiD]

As discussed in a few PRs in the last few days, I'd like to add a style guide that we can use as a guide for grammatical/language changes in descriptions etc. These should avoid debates on language, as all discussions can defer to this document, and in cases where this document does not document a style and there is not consensus, an executive decision can be made, added to this document, and then adhered to moving forward.

To get the ball rolling, I propose having a STYLE-GUIDE.md file, with a guidance and example for each point. I've put this together as a rough PR to get discussion started.

Please consider it both from the general case (how the style guide should work) and the specific points in this PR.

[SaschaMann]

Perhaps this could be the first example of an agreed spelling?

[iHiD]

Sure. But I also want a rule that explains what happens when multiple valid spellings are used without a documented decision in this guide (ie, they should be exercise-consistent)

[rpottsoh]

lowercase seems to be more popular:

https://english.stackexchange.com/questions/59409/lowercase-lower-case-or-lower-case
oO

[SleeplessByte]

Good enough for me 👍

[wolf99]

More popular != correct 😜

[iHiD]

I'd agree with lowercase, but I think this falls into the "it doesn't matter as long as its consistent within an exercise" bucket. Unless anyone feels strongly about this particular word, and wants to encode lowercase as a rule and find me another example for this bit :)

[SaschaMann]

Could you perhaps add an example of a non-maths esoteric term? The content of this section only mentions maths terms.

[iHiD]

I can't think of one off the top of my head. But I'll try and come up with one and PR it. Feel free to do the same if you can think of one.

[kotp]

I would guess that if I were talking about "lower case" it would be the beer that is lower than the other case of beer. While saying "lowercase" is talking about letters.

[ceddlyburge]

The freecodecamp editorial guide is good and has some stuff about simple language. One thing it mentions is not to use Latin things like e.g, and instead use English things, like for example.

[SaschaMann]

general case (how the style guide should work)

I think in general it may be a good idea to have a rule that exercise-specific style decisions overrule the general style guide if they are necessary or reasonable in the context of the exercise.

[iHiD]

@ceddlyburge Nice!

I think in general it may be a good idea to have a rule that exercise-specific style decisions overrule the general style guide if they are necessary or reasonable in the context of the exercise.

I'm ok with this in principle. However, I'd probably want that signing off by other maintainers as a valid exception, rather than being something that maintainers can just arbitarily override. Else we risk a "rogue" maintainer who doesn't want to adhere to the rules just making "exceptions" for all their exercises (I'm thinking track-specific overrides). ie, we should all adhere to these rules Exercism-wide unless there's a specific situation where a cohort of maintainers agree there's a valid exception.

I'd also like to roll this guide out to mentoring and stuff further down the line too.

That said, I'm not sure of a situation where the style-guide should be overriden. Do you have an example?

[SaschaMann]

However, I'd probably want that signing off by other maintainers as a valid exception, rather than being something that maintainers can just arbitarily override.

I agree. I also think it should explicitely be documented in the exercise itself, not just in a git commit/PR.

That said, I'm not sure of a situation where the style-guide should be overriden. Do you have an example?

I can't think of a specific example right now.

[iHiD]

I've "resolved" all the discussions that are blocked, so I'm going to merge so we've got a document on master that people can add to. Let's continue any discussions on individual PRs, so this doesn't become a huge PR (we're already at 2x comments to LOCs 😉).

Thanks everyone 🎉