language-tracks/configuration/exercises.md - document reasons a topic should be added

[petertseng]

trafficstars

In this issue, we discuss how to decide when to add topics to an exercise. Discussion seems to favour adding only topics that are essential/required for an exercise. To close this issue, all that would be left to do is to document this.

Original issue text:

---

It is possible to see that the current https://github.com/exercism/docs/blob/master/language-tracks/configuration/exercises.md#topics tells us

We show the topics for an exercise on the website. This lets people optimize the learning experience to their own interests—skipping topics that they are not interested in, or that they already know a lot about, and doing deeper dives into topics that they're curious about.

Recently in https://github.com/exercism/rust/pull/558#discussion_r197054489 I had questoins about when it is appropriate to add a topic.

Should a topic be put if it is possible that a solution might use it? Or should it only be put if a solution must use it (perhaps because the tests require it), etc.? Or are we supposed to exercise judgment and include a topic if we think any reasonable solution would use it? But what constitutes reasonable? etc.

I have now understood that the stated goal of topics is to allow a student to optimise the learning experience, though now I am pulled in both directions. Let's take the specific question of "should regular_expressions be added as a topic to pig-latin" to illustrate.

• I think I should add it if it is merely a possible solution, since students looking for a good opportunity to use regular expressions should get all opportunities available
• Actually no, I think I should only add it if it is required, because I wouldn't want someone who wants to skip regular expressions to unnecessarily skip this exercise just because they think it would force regular expressions

Having said those two things, I think it's a questoin of whether we try to optimise for one of those two cases... or something else, since those are not the only choices. So, what is the reasoning you choose to use when deciding topics?

(I understood from https://github.com/exercism/discussions/issues/167 that topics are hard, though a large part of the discussion there was whether to have consistency between the different tracks, whereas I'm having trouble even deciding what to do for any one track, never mind multiple!)

[ErikSchierboom]

So, what is the reasoning you choose to use when deciding topics?

I have to admit that I think the C# and F# track isn't very consistent in choosing the topics, freely use both goals. That said, I think it is good to discuss this, so thanks for bringing this up.

What I think we should aim for is to describe what the core topic of the exercise is. What fundamental topic will always hold when dealing with the exercise. That should I think exclude possible topics, that depend on an implementation, such as suggesting a regular expression for the pig-latin exercise, unless of course, you really want people to only solve it using regular expressions (which would be to limiting I think).

[wolf99]

IMHO requirements should not be indicated through topic tags.

I would agree with @ErikSchierboom, to take the pig-latin example, I would likely mark this with a strings topic. The exercise concerns string handling but the student can perform that string handling in any way they choose that satisfies the tests.

Then, if the exercise is specifically intended to have the student use regular expressions then that is a requirement and it should be specifically mentioned in the exercise readme rather than relying on the student to draw requirements by observing topic tags (it likely should be added as a second topic also).

[coriolinus]

It might be useful to handle topics at the problem specifications level and then let individual tracks make modifications as necessary, instead of leaving everything to the individual tracks. I think our best chance of achieving some kind of consistency across tracks and exercises is by handling it that way.

On Sun, Jun 24, 2018, 13:52 toby [email protected] wrote:

IMHO requirements should not be indicated through topic tags.

I would agree with @ErikSchierboom https://github.com/ErikSchierboom, to take the pig-latin example, I would likely mark this with a strings topic. The exercise concerns string handling but the student can perform that string handling in any way they choose that satisfies the tests.

Then, if the exercise is specifically intended to have the student use regular expressions then that is a requirement and it should be specifically mentioned in the exercise readme rather than relying on the student to draw requirements by observing topic tags (it likely should be added as a second topic also).

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/exercism/docs/issues/115#issuecomment-399750787, or mute the thread https://github.com/notifications/unsubscribe-auth/AHdeTvr4A4GiC__7JoclrTz5IEz32IaHks5t_31ygaJpZM4UzRfh .

[Stargator]

I think the primary goal is to have topics that are broad and not specific to how the problem will be solved. For example, on the Dart track we have our solution solving the problem in a specific way using enums. The author of adding that problem to the track may only see that as the way to solve the problem, but there are certainly other ways around it.

[petertseng]

It might be useful to handle topics at the problem specifications level

Agreed that it might be useful. I used https://github.com/exercism/exercism/issues/4186 to discuss some particulars of the approach.

To summarise my read of answers from those gathered here, it appears that we favour topics that are essential to the problem and/or without a doubt necessary to to solve the problem, rather than those that are merely a possibility for solving the problem. Examples of support:

describe what the core topic of the exercise is. What fundamental topic will always hold when dealing with the exercise

The exercise concerns string handling but the student can perform that string handling in any way they choose that satisfies the tests.

if the exercise is specifically intended to have the student use regular expressions then that is a requirement and it should be specifically mentioned in the exercise readme [...] (it likely should be added as a second topic also)

think the primary goal is to have topics that are broad and not specific to how the problem will be solved.