Describe representer docs (#384)

* Document exercises/shared/.docs/representations.md file

* Describe REPRESENTER_NORMALIZATIONS.md document

Author: ErikSchierboom

building/tracks/docs.md

@@ -1,15 +1,16 @@
 # Docs
 
-Each track must have a `docs` directory with the following (required) files:
+Each track must have a `docs` directory with the following files:
 
 ```
 docs
-├── ABOUT.md
-├── INSTALLATION.md
-├── LEARNING.md
-├── SNIPPET.txt
-├── RESOURCES.md
-└── TESTS.md
+├── ABOUT.md (required)
+├── INSTALLATION.md (required)
+├── LEARNING.md (required)
+├── SNIPPET.txt (required)
+├── REPRESENTER_NORMALIZATIONS.md (optional)
+├── RESOURCES.md (required)
+└── TESTS.md (required)
 ```
 
 ---
@@ -132,6 +133,119 @@ let hello = "Hello, World!"
 
 Check [this page](https://exercism.org/tracks/fsharp) to see what this looks like when rendered (note: you must not have already joined the track).
 
+## File: `REPRESENTER_NORMALIZATIONS.md`
+
+**Purpose:** List the normalizations the representer applies to a solution.
+
+**Displayed on:**
+
+(not displayed)
+
+### Example
+
+````markdown
+# Representer normalizations
+
+The representer applies the following normalizations:
+
+## Remove comments
+
+All comments are removed.
+
+### Before
+
+```fsharp
+module Fake
+(* Block comment
+   on multiple lines *)
+let message = "Hi" (* Block comment after code *)
+// Double-slash comment on single line
+let reply = "Yo" // Double-slash comment after code
+/// <summary>This function adds two numbers</summary>
+/// <param name="x">The first number</param>
+/// <param name="y">The second number</param>
+/// <returns>The first number added to the second number</param>
+let add x y = x + y
+```
+
+### After
+
+```fsharp
+module Fake
+let message = "Hi"
+let reply = "Yo"
+let add x y = x + y
+```
+
+## Remove import declarations
+
+All import declarations are removed.
+
+### Before
+
+```fsharp
+module Fake
+open System
+open System.IO
+let message = "Hi"
+```
+
+### After
+
+```fsharp
+module Fake
+let message = "Hi"
+```
+
+## Format code
+
+The code is formatted using the [fantomas library](https://fsprojects.github.io/fantomas/docs/index.html).
+This formats the code according to the F# style guide.
+The full list of transformations that are applied by fantomas can be found [here](https://fsprojects.github.io/fantomas/docs/end-users/Configuration.html).
+
+### Before
+
+```fsharp
+module Fake
+let  add ( birthDate  :  DateTime)  =
+    birthDate.Add (    2.0)
+type Volume =
+| Liter of float
+| USPint of float
+| ImperialPint of float
+```
+
+### After
+
+```fsharp
+module Fake
+let add (birthDate: DateTime) =
+    birthDate.Add(2.0)
+type Volume =
+    | Liter of float
+    | USPint of float
+    | ImperialPint of float
+```
+
+## Normalize identifiers
+
+Identifiers are normalized to a placeholder value.
+
+### Before
+
+```fsharp
+module Fake
+let foo x = x + 1
+```
+
+### After
+
+```fsharp
+module PLACEHOLDER_1
+let PLACEHOLDER_3 PLACEHOLDER_2 = PLACEHOLDER_2 + 1
+```
+````
+
 ## File: `RESOURCES.md`
 
 **Purpose:** Links to useful resources.

building/tracks/presentation.md

@@ -25,6 +25,7 @@ These file are shared between all exercises:
 
 - `debug.md`: explains how a student that is coding in the browser can still do "debugging" (optional)
 - `help.md`: contains track-specific instructions on how to get help (required)
+- `representations.md`: explains which normalizations are applied to a solution to create its representation (optional)
 - `tests.md`: contains track-specific instructions on how to run the tests (required)
 
 See the [shared files documentation](/docs/building/tracks/shared-files) for more information.

building/tracks/shared-files.md

@@ -4,6 +4,7 @@ Some documentation files apply to both [Concept Exercises](/docs/building/tracks
 
 - `debug.md`: explains how a student that is coding in the browser can still do "debugging" (optional)
 - `help.md`: contains track-specific instructions on how to get help (required)
+- `representations.md`: explains which normalizations are applied to a solution to create its representation (optional)
 - `tests.md`: contains track-specific instructions on how to run the tests (required)
 
 The [Presentation document](/docs/building/tracks/presentation) describes how these files are used to present content to the student.
@@ -58,6 +59,33 @@ This document should **not** link to Exercism-wide (track-agnostic) help resourc
 If you're having trouble, feel free to ask help in the C# track's [gitter channel](https://gitter.im/exercism/csharp).
 ```
 
+## File: `representations.md`
+
+**Purpose:** Explains which normalizations are applied to a solution to create its representation
+
+**Presence:** Optional
+
+When a track has implemented a [representer](/docs/building/product/representers), each submitted solution will have a representation created for it.
+
+This document should list all the normalizations the representer applies to a solution.
+
+This helps a mentor while adding representation comments.
+
+### Example
+
+```markdown
+# Representations
+
+The representer applies the following normalizations:
+
+- All comments are removed
+- All import declarations are removed
+- The code is formatted
+- Identifiers are normalized to a placeholder value
+```
+
+If your track has a `docs/REPRESENTER_NORMALIZATIONS.md` file, we recommend to link the normalizations to the corresponding section in that file.
+
 ## File: `tests.md`
 
 **Purpose:** Contains track-specific instructions on how to run the tests