It's time to prepare your track for the nextercism prototype

[kytrinyx]

TL;DR: if you accept the pull request with the new exercise configuration defaults then your track will be included in the nextercism prototype. If you want your track to feel like it really fits into the new prototype, then choosing a handful of core exercises and making these prerequisites for optional exercises will make it amazing.

---

Background

In #159 we hammered out the details of the new exercises structure in config.json. I've opened pull requests in all the tracks with defaults for all exercises (see tracking issue in exercism/meta#16). Additionally we're trying to figure out how to best manage exercise topics (#167).

@nicolechalmers has been working on designs and wireframes for the Exercism redesign for several weeks now, and recently @ccare and @iHiD started building a prototype to explore those designs. We hope to have something ready for maintainers and contributors to try out in the next couple of weeks.

One of the key differences in the new prototype is how we're structuring exercise progression. Instead of a track consisting of a long, linear chain of exercises to be completed in order, there will be a short, linear chain of core exercises that are required in order to complete the track, each of which will unlock a number of optional exercises that can be completed in any order (or not at all).

Preparing for launch

So! This is where it gets exciting.

By default, if you accept the pull request with the default exercise configurations, then your track will be included in the nextercism prototype. If no exercises in a config.json have been marked as core, we pick core exercises automatically, meaning your track will have the following behaviour:

• the first 8 exercises in the file become core
• all other exercises are optional and can be done without completing any prerequisites

As soon as you update one exercise to be core, we will then respect the core field in the config.json.

For each track, we are aiming for between 8 and 20 core exercises. If your track has 100 exercises, then we'll ideally have ~15 core with each unlocking 5 or 6 optional exercises. If you have fewer than 20 exercises, then prioritize choosing a fun and useful core pathway of 8-10, and then each can unlock 1 or 2 optional exercises.

A great core exercise:

• is different from all the other core exercises
• has many possible approaches/solutions

If you have some exercises that seem more popular than others, then they might be a good starting point for core exercises. Eventually we would like to make it so that a track broadly covers the language features and standard library, but that will take more thought and work.

So for now, just picking a set of core exercises and deciding what unlocks what is a great start.

A few nitty-gritty details

If you have topics and difficulties set, then you could make a first pass at guessing 'core' by taking the simplest exercise that introduces a topic, and making that core. Then make all the other exercises for that topic unlocked by that core exercise. This is in no way perfect or automate-able but it could give you a starting point for discussion.

Try to have 3 or so exercises that are core: false and unlocked_by: null. These will become immediately available to people after they submit their first iteration of the first core exercise. That way people will have some extra exercises to work on while they wait for feedback.

Aside from those initial optional exercises, all other optional exercises (core: false) should be unlocked_by the slug of a (a single) core exercise.

As you implement these changes, it would be great to hear you report back here what you found interesting or difficult, or what insights you had, or what process you used to make the change. This can help other track maintainers make the change in their track.

[katrinleinweber]

Thanks for the summary :-) I found it difficult to juggle in my head the tree that the new config.json structure creates. Are there any quick online visualiser tool? Maybe with the exercises as nodes and the edges drawn according to unlocked_by? Maybe even with cross-cutting "levels" through the tree according to difficulty? I imagine something like a simpler version of this graph mixed with a user story map?

[stkent]

Eventually we would like to make it so that a track broadly covers the language features and standard library, but that will take more thought and work.

How disruptive might this later change be for users? In the Java track, I'm inclined to wait until the various topics discussions have ended so that our first attempt can be informed by exercise topics, because significant changes to the tree feel more likely to confuse users than in the old linear model.

[kytrinyx]

Are there any quick online visualiser tool?

That would be incredibly handy. @iHiD do you know of anything?

How disruptive might this later change be for users?

That's something we've discussed quite a bit. If they have unlocked an exercise, then they will always be able to access it, even if we move things around or change prerequisites.

If we take what used to be a core exercise and make it an optional one, then it will visually change their progress, but it should still make sense. We are also considering what kind of messaging would mitigate this.

[stkent]

👍

So, what would be net most beneficial to ya'll and to users in the long run:

• having as many tracks as possible opted in early to the new structure, even if it involves a more significant shuffle in the future;
• having tracks wait for topic definition to be solidified, then applying topics, then ordering based on those topics - delaying opting in to the new structure - to minimize future shuffling

[iHiD]

@stkent Great questions.

• I think we need all tracks in by 1st September (our big target launch date) and as many as possible in the prototype (1st Aug).
• Ideally I'd say that we get all the PRs merged in the next week, then maintainers have a month to experiment on the prototype and get things how they feel comfortable. The only people using the site in Aug will be maintainers and people who are expecting breaking changes (we're planning on wiping the whole db at least twice to test things for example).
• The key thing for me is choosing the core exercises. The rest can come later, but a good solid 8-15 core exercises would make the track feel rich. Adding the locking will then make it feel pro.

Does that help clarify things?

[iHiD]

@katrinleinweber Great question. No there aren't but from Aug 1st you can experiment with the structure and see it update live(ish) on the prototype.

However, I think it's a lot simpler than you perceive (based on the images you linked).

There are three states that an exercise has:

1. Core exercise - part of a linear track. Complete these and you "complete the track". Set by core: true
2. Bonus exercise - not part of anything linear, floating and free. Great for practicing and trying things. Always available. Set by core: false
3. Dependant bonus exercise - Part of the pool of bonus exercises, but locked until you complete the core exercise that unlocks it. Set by core: false, unlocked_by: "bob"

Here's my best ascii art intepretation (number representing the state as above)

          [ 1 ] -> [ 1 ] -> [ 1 ] -> [ 1 ]
            |                 |
         ---------        ---------
         |   |   |        |   |   |
[2] [2] [3] [3] [3] [2]  [3] [3] [3] [2] [2] [2]

Does that help or just cause more mental chaos (which I'd totally understand!)

[katrinleinweber]

Yep, helps, thanks! But also helps the feature creep sentiment ;-> A tool to generate the JSON, based on drag'n'dropping the exercises into the tree structure :-D

[kytrinyx]

A stand-alone, open source tool! It would be awesome.

[rchavarria]

I just created this gist. It's absolutely nothing to be proud of, but it might help someone out there.

Transform part of your config.json into a CSV file

It's a script, to be run on NodeJS. It just reads the config.json file, gets the list of exercises, and creates a CSV line for each exercise with these attributes: slug, core and unlocked_by.

I used it to import the CSV file into a spreadsheet and it allowed me to see at a glance core/non-core exercises, and more or less what exercises could unlock other ones.

Edit: fix link to gist, thanks to @iHiD for catching it

[iHiD]

@rchavarria Awesome. That doesn't render for me for some reason but this version does.

[Insti]

Is anyone working on building this exercise tree based on the common problem-specifications?

I will not be working on this, but would help update the Ruby track if such a list is made and I can just copy/paste the relevant sections into the config.json

[kytrinyx]

@Insti while I think that some languages might have some overlap, I don't think that it is possible to make a canonical tree for problem-specifications. I'd love to see that as a starting point, though—it would probably be easier to tweak something than to make something up.

[jonmcalder]

I've hacked together a basic config visualization tool which might be of use to other maintainers while iterating on the config.json files for their various tracks. You can access it via shinyapps.io for now, but I'm on the free tier so can't guarantee its availability.

Alternatively if you're not averse to R you can run it locally - just checkout the instructions in the README and ping me if anything is unclear or if you run into any issues. Also feel free to open an issue or pull request there if you think this is worth developing further.

Below is part of the network tree from @rchavarria's WIP branch for the JavaScript track.

[kytrinyx]

@jonmcalder this is pretty brilliant!

[robphoenix]

@kytrinyx @iHiD Is there going to be any kind of visualisation of each track's exercise structure, similar to what @jonmcalder has done above, on the Nextercism website?

[kytrinyx]

@robphoenix No, we're not considering a full visualization at the moment.

[iHiD]

@jonmcalder That's really awesome. Thanks!
@robphoenix A user will be able to access all that info but not in a tree view like that. eg. the core track appears linear and you can see which exercises were unlocked by which core, and you can filter by topic on the extra exercises, all through the main UI.

[robphoenix]

@kytrinyx @iHiD ok, grand, sounds good!

[ErikSchierboom]

For each track, we are aiming for between 8 and 20 core exercises. If your track has 100 exercises, then we'll ideally have ~15 core with each unlocking 5 or 6 optional exercises.

I am looking into defining the core exercises, but as it has over 100 exercises, which I find makes choosing 15 core exercises a bit hard. My main problem is: what should I be focusing on? If I focus on introducing as many language features as possible, the end result is that all exercises in the core will have a relatively low difficulty (1 to 5). Would that be okay?

Another problem I have is that some topics are explained best in a very simple exercise, but is far more interesting in a (slightly) more difficult exercise. I have to balance between fun and ease of learning here, which is also hard I feel.

[iHiD]

If I focus on introducing as many language features as possible, the end result is that all exercises in the core will have a relatively low difficulty (1 to 5). Would that be okay?

@ErikSchierboom Yes - I think so. If a beginner can do the core track, and learn loads of concepts without it being too difficult, I think that's good. Then then can practice with the others exercises, where we clearly expose difficulty, so they can make those decisions as they choose each exercise to do.

Saying that, I think if there's a slightly more difficult exercise that explains the same thing and is more fun, I would edge towards that. But if it moves into being too difficult, I'd say keep it as a side-exercise.

[ErikSchierboom]

Thanks for the quick reply! I'll see what I can come up with. It'll probably need several iterations anyway.

[jonmcalder]

Thanks @ErikSchierboom for asking this question and to both you & @iHiD for sharing some of your thoughts. I had a similar sense with this too, although in the case of the R track since it's very new we've got < 30 exercises and they're all pretty low difficulty.

My guess is that a natural starting point will be to try and cluster exercises around topics to begin with - i.e. with an easy-ish core exercise that is (ideally) both interesting and offers a reasonable introduction to a topic area, with that exercise then unlocking (possibly) harder exercises which share one or more similar topics. That way, someone can continue with the core progression if they want to explore different topic areas, or do more of the just unlocked exercises to solidify understanding of the current topic/concept/theme (or just to challenge themselves). Like @iHiD suggests though, the core exercises may well not be the easiest ones if there are slightly harder exercises which are better or more fun examples within a topic area.

Obviously needs will differ depending on the language and what ways it makes sense to introduce topics - especially given that different combinations of topics can be surfaced by the same exercise depending on the language. I agree that in most cases it will probably need lots of iteration once we start familiarizing ourselves with how the new progression structure plays out.

Also - another shameless plug for the tool I created last week which is relevant to this discussion: made a small update over the weekend which allows for sizing of the nodes according to their difficulty. This is illustrated below using your proposed/WIP progression for the csharp track (which looks like a really good start to me by the way!). Note how you've got a nice difficulty progression within the core track (blue nodes getting bigger) and the side exercises (red nodes) are generally harder than the core exercise which unlocks them.

The above visual does highlight a small mistake though:

...
"slug": "bank-account",
"core": true,     # I think you meant for this to be false?
"unlocked_by": "clock",
...

bank-account should either be core or unlocked by clock - not both.

There are also some nice examples of clustering around a central topic, e.g. classes (shown below)

PS Hope you don't mind me using your config as an example here - the R track's progression is less interesting to visualize given the low number of exercises. Long way to go still!

[ErikSchierboom]

@jonmcalder That's great information and the tool is very helpful! And you did indeed find a bug. Thanks for the help.

[ErikSchierboom]

@kytrinyx Should we be keeping a list of the track that have implemented the new structure?

[kytrinyx]

@ErikSchierboom No, I'll write a script that figures that out if we need to know. For now we're defaulting to some simple "workable" choices for the tracks that haven't. Once we see everything live on the prototype (hopefully next week!) then we will know more about what we need to ask all the maintainers to do to prep their tracks properly.

[kytrinyx]

The site has launched! I'm going to go ahead and close this, and if we have specific things to ask of you we'll open issues in individual tracks. Thanks, everyone!