Move style guide to standards documents (exercism#73)

Author: ErikSchierboom

anatomy/tracks/README.md

@@ -35,7 +35,7 @@ Some parts of the track can be displayed in [widgets](./widgets.md), such as [co
 
 ## Style guide
 
-The [style guide](./style-guide.md) records how documents should be written and formatted.
+All documents should adhere to the [style guide](../../contributing/standards/style-guide.md). Markdown documents should also adhere to our [Markdown standards](../../contributing/standards/markdown.md).
 
 ## Example
 

anatomy/tracks/style-guide.md

@@ -2,7 +2,7 @@
 
 The following is the way that all Markdown files within Exercism should be structured.
 
-Some of the rules in this document are not yet implemented across all of Exercism. 
+Some of the rules in this document are not yet implemented across all of Exercism.
 We welcome PRs to fix them.
 All rules are being added to our CI and linting tools, and should be adhered to for new changes.
 
@@ -14,13 +14,93 @@ All rules are being added to our CI and linting tools, and should be adhered to
 - No heading may decend a level greater than one below the previous (e.g. `##` may only be followed by `###`, not `####`).
 - Beyond the single level-1 (`#`) heading, only level-2 (`##`), level-3 (`###`) and level-4 (`####`) headings may be used.
 
+## Links
+
+Please use [reference links](https://spec.commonmark.org/0.29/#reference-link), which are defined at the bottom of the Markdown file, mapped to a reference slug, and referenced by that slug in the text.
+
+This method makes maintenance easier, since link only have to be updated in a single location.
+
+Example:
+
+```
+I have a paragraph of text that links to the same page twice.
+
+The [first link][indirect-reference] in one sentence.
+
+Then, another sentence with the [link repeated][indirect-reference].
+
+[indirect-reference]: https://example.com/link-to-page
+```
+
+Links should always have anchor text, instead of putting the URL itself into the text. For example, the following does not use anchor text, and is harder to read.
+
+```
+If you want some more information, please visit https://google.com.
+```
+
+Using anchor text and linking it is easier to understand and contextualize.
+
+```
+If you want some more information, [Google][google-search-link] is a useful resource.
+
+[google-link]: https://google.com
+```
+
+Which renders as, "If you want some more information, [Google](https://google.com)".
+
+## Code
+
+Whenever one refers to code elements (e.g. functions or keywords), the code should be wrapped in backticks:
+
+```
+- The `printf()` function writes to the console.
+```
+
+Which renders as:
+
+- The `printf()` function writes to the console.
+
+More complex code (e.g. multiline code) should be wrapped in triple backticks. A [language identifier](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml) should be specified after the opening triple backticks to enable syntax highlighting:
+
+````python
+```python
+# Define a variable
+album = "Abbey Road"
+```
+````
+
+When possible, format code in a way that is most relevant to the environment it is being presented in. If available, please reference the docs for your language.
+
+For example, Python has the REPL (read-eval-print loop), which allows a programmer to type code directly into a terminal. If a user was debugging some code, or running a function locally to test/observe how it works, they are more likely to use a REPL to do so, since it is more convenient to type interactively there. In this situation, we prefer formatting example code as if it was being typed into the REPL, with a leading `>>>`:
+
+```python
+# This is the expected output a student would see while testing a function they wrote.
+>>> print(extract_message("[INFO] Logline message"))
+'Logline message'
+```
+
+In other cases, it makes more sense to leave code formatted as if it was in a `.py` file. Here, the student benefits by being presented with something that mimics how they would write the code themselves.
+
+```python
+# presenting how functions are defined in Python:
+def sample_func(argument1):
+    pass
+```
+
+A quick way to distinguish between the two cases when it's unclear - if this is code the student can run in a terminal, format it that way. If it's code that Exercism might run (in tests, library code the student will write, etc), default to formatting it as runnable code.
+
+## Language Code Style
+
+Please consult each language's docs folder for more information on the preferred style conventions for that language. All exercises of a language should use a consistent coding style.
+
 ## Layout
 
 ### One sentence per line
 
 Paragraphs should be laid at using one sentence per line. The [Ascii Doctor docs][asciidoctor] explain the logic of this clearly.
 
 For example, a single paragraph should be laid out as follows:
+
 ```
 Exercism has been designed, engineered and built by thousands of very talented individuals.
 Nearly everything with Exercism has been debated, discussed and rewritten many times.
@@ -35,12 +115,24 @@ Exercism is a very intentional product - things are there because they've been d
 ## Linters
 
 There are various rules you can use to configure linters to meet this spec:
+
 - Enable [MD001](https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md#md001---header-levels-should-only-increment-by-one-level-at-a-time)
 - Enable [MD002](https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md#md002---first-header-should-be-a-top-level-header)
 - Use `atx` for [MD003](https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md#md003---header-style)
 - Disable [MD013](https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md#md013---line-length)
 - Disable [MD033](https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md#md033---inline-html)
 
+## Auto formatting
+
+Some repositories use [prettier](https://prettier.io/) to ensure that all Markdown is formatted consistently. This can result in the following benefits:
+
+- No formatting discussions.
+- Great editor/IDE integration so files can be formatted on save.
+- Easy to add CI checks for formatting.
+- Easy to automatically format files using a script.
+
+All the above can greatly help reduce churn in reviews, whch is frustrating for both the reviewer and the reviewee.
+
 ---
 
-[asciidoctor]: https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line
+[asciidoctor]: https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line

contributing/standards/markdown.md

@@ -4,44 +4,48 @@ This document acts as a Style Guide for the language and wording used in exercis
 
 ## Application
 
-These rules should be followed in all exercises. 
+These rules should be followed in all exercises.
 Existing descriptions and test-cases can be updated to adhere to them without requiring "replacement" test cases.
 
 ### Consistency within an exercise.
 
-There are some terms that have multiple valid spellings (e.g. "lower case" vs "lowercase"). 
+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.
 
 ### Exceptions
 
-Exercises may vary from these rules if there is general consensus across maintainers that this is reasonable. 
+Exercises may vary from these rules if there is general consensus across maintainers that this is reasonable.
 For example, an exercise about converting between different units might choose not to use SI measurements.
 
 ## Language
 
-All content should be written in US English. In the future other translations may occur, but the "official" Exercism language is US English.
+All content should be written in US English, which differs from UK English in a [variety of ways](https://en.wikipedia.org/wiki/Comparison_of_American_and_British_English). In the future other translations may occur, but the "official" Exercism language is US English.
 
 ### Measurements
+
 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.
 
 ### Abbreviations, acronyms and initialisms
 
 Abbreviations, acronyms and initialisms are often more difficult to understand than other phrasing options, and can alienate people trying to learn.
 
 Many abbreviations are jargon. Avoid jargon where possible by using alternative language. Don't use abbreviations unless either:
+
 - The abbreviated term is better known than the unabbreviated term
 - The text will be excessively verbose without abbreviation
 
 When using abbreviations always explain what the term means on its first use. This will often, but not always, include expanding the abbreviation. It will rarely be sufficient to only expand the abbreviation.
 
 Here are some example rules:
+
 - Prefer "if I recall correctly" to "IIRC"
 - Prefer "as far as I know" to "AFAIK"
 - Prefer "queue" to "FIFO" and "stack" to "FILO"
 - Instead of describing an interface as "RESTful", describe it's specific properties
 - If you must use "CRUD", explain that it stands for Create, Read, Update, Delete and that these are the basic actions in standard databases
 
 An some examples of good usage:
+
 - "HyperText Markup Language (HTML) is the language used to describe document structure and content on the web" _(expanded and explained)_
 - "DNA, a set of chemical instructions that influence how our bodies are constructed" _(DNA is not expanded because "deoxyribonucleic acid" is unlikely to help explain what DNA is to our audience)_
 - "NASA, the United States' space agency, launched the Mariner 2 space probe in..." _(NASA is not expanded because the "National Aerospace and Space Administration" is much better known by its acronym than by its expanded name)_
@@ -56,6 +60,7 @@ Use the "[Oxford Comma](https://en.wikipedia.org/wiki/Serial_comma)" (also known
 #### Exceptions
 
 Some abbreviations are considered common, useful, and non-technical enough that we have decided to permit them:
+
 - `e.g.` or `eg`
 - `i.e.` or `ie`
 - `etc.` or `etc`
@@ -70,6 +75,7 @@ Contractions (e.g. "won't", "I'm", "that's") should be used sparingly if at all
 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)".