Add representer feedback document (#385)

Author: ErikSchierboom

mentoring/README.md

@@ -4,4 +4,5 @@ Welcome to the Exercism Mentoring Team. Follow the links below for guides on how
 
 - [Choosing a Solution](/docs/mentoring/choosing-a-solution)
 - [How to give great feedback](/docs/mentoring/how-to-give-great-feedback)
+- [How to give feedback on representations](/docs/mentoring/how-to-give-feedback-on-representations)
 - [How to use Markdown in mentoring](/docs/mentoring/markdown)

mentoring/config.json

@@ -23,6 +23,14 @@
     "title": "How to give great feedback",
     "blurb": "You've chosen an exercise to mentor - now give some great feedback."
   },
+  {
+    "uuid": "80d6d993-ccf8-433f-af03-44b171328470",
+    "section": "mentoring",
+    "slug": "how-to-give-feedback-on-representations",
+    "path": "mentoring/how_to_give_feedback_on_representations.md",
+    "title": "How to give feedback on representations",
+    "blurb": "Considerations for giving feedback on representations."
+  },
   {
     "uuid": "57f323a6-29ea-43ef-9936-af44162ccc64",
     "section": "mentoring",

mentoring/how_to_give_feedback_on_representations.md

@@ -0,0 +1,20 @@
+# How to give feedback on representations
+
+Giving feedback on a representation is different from giving feedback on a single solution.
+
+## Representation feedback applies to multiple solutions
+
+The key thing with representation feedback is that they apply to _multiple_ solutions.
+Anything that the representer normalizes should not be commented on, as you have no way of knowing what the original syntax was for a particular solution.
+
+As an example, many representers normalize a solution's white space.
+Therefore, even though the solution shown in the representation feedback UI might have formatting issues, you shouldn't comment on it as other solutions with the same representation might not have those formatting issues.
+
+Another example is naming of variables, functions, methods or classes.
+As representers could normalize identifier names, you shouldn't comment on them.
+Even if your representer currently does _not_ normalize identifier names, you still should not comment on it, as this is a normalization likely to be added to a representer later.
+
+## Don't duplicate analyzer comments
+
+As students will get to see both representer _and_ analyzer comments, make sure that you don't duplicate comments.
+To help with this, the analyzer comments are shown on the representation feedback page.