diff --git a/STYLE-GUIDE.md b/STYLE-GUIDE.md new file mode 100644 index 0000000000..96180170da --- /dev/null +++ b/STYLE-GUIDE.md @@ -0,0 +1,23 @@ +# Exercism's Style Guide + +This document acts as a Style Guide for the language and wording used in exercises. + +## General principle + +All content should be written in US English. +All units of measurement must be [SI](https://en.wikipedia.org/wiki/International_System_of_Units) or [SI-derived](https://en.wikipedia.org/wiki/SI_derived_unit) units. +In the future other translations may occur, but the "official" Exercism language is US English. + +## Explain or substitute mathematical and esoteric terms. + +In any place that mathematical terms are used they should be explained or substituted out for terms that require less domain knowledge. + +Examples: +- Rather than using "natural numbers", we should use "positive whole numbers". +- If we want to use the phrase "rational numbers", it must be explained in the introduction to the exercise. +- Rather than using the word range (which can have different meanings in different contexts) use "x < ? < y (greater than x and less than y)". + +## Use consistency within an exercise. + +There are some terms that have multiple valid spellings (e.g. "lower case" vs "lowercase"). +Where a consistent style has not been agreed within this document, these must be consistent within an exercise.