Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add representer feedback document #385

Merged
merged 1 commit into from
Sep 30, 2022
Merged

Add representer feedback document #385

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions mentoring/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
8 changes: 8 additions & 0 deletions mentoring/config.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
20 changes: 20 additions & 0 deletions mentoring/how_to_give_feedback_on_representations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.