Add mentoring docs (#171)

Author: iHiD

mentoring/choosing_a_solution.md

@@ -0,0 +1,76 @@
+# Choosing a solution to mentor
+
+The first decision you need to make as a mentor is which solution to mentor.
+
+## Working with the Queue
+
+You can find a list of all solutions that have been submitted for mentoring in the [Mentoring Queue](/mentoring/queue).
+The UI should look something like this:
+
+[TODO: Image of queue].
+
+If you have a particular student you'd like to mentor, you can search using the filter box, and you can order by oldest or most recent.
+On the right-hand side you can filter by language or exercise.
+You can also choose to only show exercises you've completed yourself (enabled by default), which is often wise as you will struggle to give great feedback if you've not wrestled with solving the exercise yourself.
+
+The main table shows the exercise, the student and when they requested mentoring.
+Hovering on a row gives you lots more detail.
+You can see more about the user: their name, location and reputation (which is a great indicator of whether they are a contributor or mentor themselves) and also how many times they've been mentored before.
+You'll also see some blurb they've written explaining what they're looking to get out of the track.
+As you start mentoring people, you'll also see whether you've mentored them before, and if you've favourited them,
+
+The blurb on the tooltip is a great first indicator about whether this student is right for you.
+Do their knowledge gaps match your expertise?
+If they say they're looking to get good at functional programming, can you help with that?
+If they new to the language and looking to learn the basis, then if you have **any** real experience, you'll probably be able to help, but if they've been programming in that language for years and trying to hit expert-level, you'll need to have a pretty solid grasp of the language yourself.
+
+Once you've found a solution that looks like it might be good, we can take the next step and have a look at the code.
+So click on that solution and enter the Mentoring Discussion UI
+
+## The Mentoring Discussion UI
+
+At this stage you're looking at someone's solution, but haven't yet committed to mentoring it.
+You first have the opportunity to read their code and get some other information, before starting.
+
+**If you're new to this UI, it might feel a little overwhelming as there is a lot of information, but don't worry - it'll soon become familiar.**
+
+### The student's code
+
+On the left hand side of the screen is the student's code.
+The UI will look something like this:
+
+[TODO: Image of mentor discussion with areas marked].
+
+1. The left hand side shows you the students code.
+   By default you'll be seeing their most recent iteration.
+   If they've submitted multiple iterations, you can switch through these using the numbers in circles at the bottom, but they've only submitted one iteration, then you won't see those icons.
+
+2. You can use the tabs at the top to switch between the student's code, the tests, and the instructions.
+   This is useful for reminding yourself about what the student has been asked to do in this exercise.
+
+3. You'll also see an indicator as to whether the tests have passed or failed.
+   If they failed, then clicking on this indicator will open a modal that shows you the specific details of their test run, so you can see what they did wrong.
+
+On the right hand side, you'll see three tabs.
+The overview tab will contain the same information about the user that you saw on the toolip.
+Below that you'll see a comment for the user about what it is that they want to learn from this specific solution.
+(For some older solutions, this might be missing).
+This is a key indicator as to whether this solution is right for you.
+Can you answer their question?
+Can you fulfil their hopes for this exercise?
+
+The third tab is called "Guidance".
+If you click on this you'll see some information that might be useful for you:
+
+- **Mentor notes:** These are community-written notes that help point other mentors towards the best way to mentor an exercise.
+  We'd really love you to help contribute your experience back to these notes.
+- **Automated feedback:** This is feedback that our analyzers have determined might be useful for you to give to a student.
+  We'll discuss this more later.
+- **Your solution:** A link back to your own solution, which you can use as a reference for how you solved the exercise.
+
+## Start mentoring
+
+If you've read the code, checked the guidance, and feel you can be helpful, then it's time to get going!
+Click the "Start mentoring" button and you'll be promoted to write your feedback.
+
+Have a read of [How to give great feedback](./how-to-give-great-feedback) next!

mentoring/config.json

@@ -6,5 +6,21 @@
     "path": "mentoring/README.md",
     "title": "Mentoring Guides",
     "blurb": "Learn how to make the most of our mentoring on Exercism"
+  },
+  {
+    "uuid": "6abb0b03-b639-4fff-9089-b0956e0209c8",
+    "section": "mentoring",
+    "slug": "choosing-a-solution",
+    "path": "mentoring/choosing_a_solution.md",
+    "title": "Choosing a solution to mentor",
+    "blurb": "Decide which solution is right for you"
+  },
+  {
+    "uuid": "3463ebad-fb50-4a7d-afeb-cbe125b181fe",
+    "section": "mentoring",
+    "slug": "how-to-give-great-feedback",
+    "path": "mentoring/how_to_give_great_feedback.md",
+    "title": "How to give great feeback",
+    "blurb": "You've chosen an exercise to mentor - now give some great feedback."
   }
 ]

mentoring/how_to_give_great_feedback.md

@@ -0,0 +1,88 @@
+# How to give great feedback
+
+At this stage you should have chosen a solution to mentor.
+If you've not, work your way through [Choosing a solution to mentor](./choosing-a-solution) first, then come back here.
+
+## Your first feedback
+
+You're now about to give your first feedback to a student.
+This can be exciting but also pretty daunting.
+A lot of (the best!) mentors suffer from [Impostor Syndrome](https://en.wikipedia.org/wiki/Impostor_syndrome) at this stage, and give up before they start.
+If you feel like that, it's totally understandable, but also almost always unnecessary.
+By the fact you're worrying about whether your feedback is going to be good enough, it's likely that you'll give thoughtful humble comments that students really appreciate.
+And in the worst case, a student can always end the discussion, and wait for another mentor, so let's give it a go!
+
+## Mindset
+
+The first thing to keep in mind is having the right mindset as a mentor.
+Students are hoping you can help improve their knowledge, and tell them things that they don't know.
+Your job isn't to "mark" their work, it's to use their solution as a basis for unlocking ideas that they are not familiar with or are struggling with.
+
+It's also worth remembering that most Exercism users are experienced developers learning a new language.
+So although their code might look bad, that may well be because they don't know how to write this language.
+Similar code in a different language might be totally idiomatic and correct.
+Conversations tend to go much better when they are approached as two peers discussing a topic, rather than one person showing off their knowledge to another.
+
+## Addressing the student's request vs teaching a new idea
+
+When a student submits a solution for mentoring, they are promoted to tell the mentor what they are hoping to get from it.
+It's really important that you as the mentor read that and try and address it in your feedback.
+
+However, one of the key values of mentoring on Exercism is that mentors can help students discover ideas they had no idea about.
+So you might look at a student's solution, read their comment which asks if there are any tweaks they could make, and think "Wow - you really don't have a grasp on this exercise at all".
+It might be that they've totally missed the point of the exercise.
+In your time as a mentor, you'll see some incredibly "overfit" solutons where students make the tests pass but totally miss the point of the challenge.
+Or see incredibly complex solutions that can be rewritten in a couple of lines of code.
+
+Your job as a mentor is to help take the student forward **from where they start**.
+What's the biggest thing you could do to help unlock an idea or unblock your thinking?
+You'll find that if you can explain an idea to a student and set a lightbulb off in their head, it'll be an incredibly rewarding discussion.
+
+## Don't just give the solution away
+
+The aim in mentoring is **not** for a student to get to the optimal solution, it is for a student to learn new things.
+Simply giving a student the correct answer is neither useful nor helpful.
+Exercism encourages students to go and look at other people's solutions and learn from them, so you giving them a good solution doesn't add any value.
+The value you add as a mentor is helping them think differently, helping them see things in a different light.
+
+Different mentors have different approaches to whether they give "hints" or "explanations".
+As a general rule, aim for somewhere between the two.
+Ensure that you tell the student enough that they can understand what they should try, but try not to just give them the answer and tell them why it works.
+
+For example, let's imagine you see an `if` statement in Ruby that would be much more nicely written using the [ternary operator](https://en.wikipedia.org/wiki/%3F:):
+
+```
+# Student's code
+if a
+  b = 1
+else
+  b = 2
+end
+
+# Mentor's suggestion
+b = a ? 1 : 2
+```
+
+You could just say "Write `b = a ? 1 : 2` instead of the `if` statement on L10.
+But that wouldn't be helping a student understand the why or have a lightbulb moment of their own.
+
+Instead it would be much better to introduce the idea of a ternary, and pose the student a challenge.
+For example: "I think you could reduce the Lines 10-14 down to one line using the Ternary Operator. How might that look?"
+A student will then have to play with that and solve it themselves, but you've given them enough info to work with.
+
+On the other end of the scale, saying "Reduce lines 10-14 to one line" wouldn't give a student any indication of how that's achievable, and so could be incredibly frustrating for them.
+So try to ensure you give enough information for a student to progress.
+
+## How much feedback should you give
+
+Different mentors have different styles, but our default suggestion is to give the most important one to three pieces of feedback on any iteration.
+If the student submits a new iteration with those solved, then you could give another one to three pieces of feedback.
+By breaking things up in that way, a student will not feel overwhelmed, but will also have enough to do to make meaningful changes each time.
+
+As you gain experience mentoring, you will get a feel for the different ways students react to different feedback, and develop a style that fits your personality.
+
+## Unsure of something? Chat to other mentors?
+
+One of the best things about being an Exercism mentor, is the community of other mentors you can learn from.
+If you've got a question about a solution, or just want to bounce ideas with other mentors, jump into our [Slack Room]() and ask away!
+You'll probably find people you can help there too 🙂