Concept introduction and about & Concept exercise introduction

CarlosHSF99 · July 10, 2023, 4:23pm

(sorry for the lack of useful links, I’m a new user, can only use 2)

I imagine this is a popular topic per this post, but not having found more discussions about it I will do it here.

From the docs

Quoting/paraphrasing Exercism’s tracks documentation:

Concept - things that a programmer would need to understand to be fluent in a language

introduction.md : provide a brief introduction to a student who has not yet completed the corresponding concept exercise
about.md : provide information about the concept for a student who has completed the corresponding concept exercise to learn from and refer back to

Concept Exercises - designed to teach specific (programming) concepts

introduction.md : introduces the concept(s) that the exercise teaches to the student

If I understood this correctly…

In a concept, before the user joins the track, it shows the about file. After the user joins the track it shows the introduction one until the user finishes the corresponding concept exercise at which point it shows the about for future reference.

In a concept exercise, there’s an introduction that gives a summarized explanation of the exercise’s concepts.

My take on this

The reason for having two concept versions is so that it first shows the more simplified version with only the necessary information to solve the concept exercise so that the user can get to writing asap.

This does seem like a good approach to keep the learner motivated, it’s like a gamification of learning. Just like in video games, you don’t want to explain everything in the tutorial, you explain the basics and let the player learn the rest playing so that they don’t get bored in the tutorial.

But shouldn’t that be the job of the concept exercise introduction? If the user wants to get to writing asap they would skip the concept and only read the exercise introduction. The concept would always be a detailed explanation.

Something strange I found is that in the Python track, the exercise Guido’s Gorgeous Lasagna introduction is as detailed as the concept about (detailed) version, minus the initial explanation about Python.

So maybe I’m missing something…

Is the concept version changing behavior explained anywhere in the website?
When is a user supposed to read the concept introduction? Not before joining the track or after completing the concept exercise as it is not there. And why before doing the exercise if it has an introduction itself (that might even be more detailed than the concept introduction, not sure about this either)?

Final observations and suggestions

I’m having trouble being concise with this post so here are some bullet points.

Cons of the current approach:

Concepts are confusing as their content changes when joining the track and completing the exercise.
Users miss the more detailed “about” page.
The about page doesn’t serve as a good reference as the users only saw the simplified version which does not have as much to refer to.
If the user is only planning to get the theory from the track, after joining they could only read the simplified versions. (“Why join then?” sure, this might not be a good point).
Having concept introduction and exercise introduction seems redundant.

Currently I’m using Exercism like this:

Go to next concept exercise.
Open and read its concepts in private mode as to have the full concept.
Quickly check if the exercise introduction has something to add.
Do the exercise.

Proposal:

Concept has a single detailed version.
Concept exercise has a simplified, aggregated version of its concepts.

Sorry for the long post, and thank you for your attention!

BethanyG · July 10, 2023, 6:16pm

Hi @CarlosHSF99

I’m a maintainer on the Python track. Thank you for posting detailed and thoughtful feedback!

First, let me explain how we tackled the concept and concept exercise docs for the Python track, which was a sort of [small] → [medium] → [large] approach:

Concept introduction.md – Brief introduction to the concept. A “teaser”. Much more about what and much less about how. Only slightly more than what you might find in a glossary definition. The one exception being for basics (that’s the Guidos Gorgeous Lasagna exercise), which just has a lot of different topics to cover.

The logic here was that students would be impatient to get to the exercise, and might get “bogged down” in reading a long explanation. Especially when they get a long-ish explanation when they work through the exercise.
Concept Exercise introduction.md – The concept introduction + enough explanation and examples to complete the exercise. But nothing more. If it is not needed for the concept exercise, it is left out of the exercise introduction.md. Additionally, if something is needed for the exercise that hasn’t been introduced in prior concepts, it is explained here in enough detail to be used by the student.

The logic for this one is that we don’t want students distracted by caveats or other usages when trying to focus on the exercise.
Concept about.md: The concept introduction (sometimes reworked with more technical details) + all of what is covered in the exercise introduction.md (related to the concept) + more/alternative usages or other considerations or caveats we deem interesting.

For many concepts in Python right now, there is not much additional content here – although we fully intend to flesh out some concepts with more details a bit further down the road. And yes - this is intended for the student to refer back to, as well as have some jumping off points to explore the concept further on their own.

Some tracks use the same document for both concept introduction.md and exercise introduction.md. Python chose not to do that since our exercise introduction.md tends to be fairly verbose, and we felt that might “bog down” or chase away students before they started. We often get feedback that students consider the concept exercise introduction docs “a wall of words”.

I agree that it can be confusing to have a short concept definition expand to a really long doc between starting and finishing an exercise. Not sure what we do about that - maybe a note upfront, or some other messaging or highlighting on the track?

I didn’t realize (or forgot) that the about.md displayed when a track was unjoined. I’d strongly prefer that the concept introduction.md (aka the concept preview) be displayed when a track is in a non-joined state. Having the about.md displayed sort of defeats the purpose of a “teaser”.

So with the current state, I am inclined to agree with you:

Having concept introduction and exercise introduction seems redundant.

CarlosHSF99 · July 10, 2023, 7:33pm

Thank you for the insight!

I assumed this is done to give a correct look of what is taught in the track to someone who is considering joining it or joining Exercism as a whole.

Suppose an experienced C++ developer is considering learning Rust on Exercism, so they check the C++ track to have a point of reference of what to expect and after gives a general look at the Rust track. If only the introductions were visible he might get a wrong idea of how good Exercism actually is. (not a comment on these tracks introductions, I haven’t actually checked them, just an example).

With the current approach I think this is really important. Something that says “This is a teaser. After the exercise is completed a more detailed version will be available for you to refer back to when you need it.”

But I still think that a better approach would be to have a single concept version to be read by more patient learners before the exercise or by more eager learners after the exercise, as reference, and an introduction to the exercise summarizing the necessary from the concepts and giving additional information needed for the exercise.

I feel that if the student wants to get to the coding without getting “bogged down” in the long explanations, they would skip the syllabus and just read the exercise introduction which are very complete already. Basically, in the [small] → [medium] → [large], I don’t see the use of the small if we have to still go through the medium to get to the exercise. And I can’t see how to omit what’s in the small from the medium without “breaking” the medium.

Obviously, this is what works for me and I’m not suggesting changing the whole website dynamic because of my experience . But it does feel like the current approach comes from a good idea that, imo, doesn’t works as well in practice. Specially the [small] → [medium] → [large] part.

iHiD · July 10, 2023, 10:15pm

In the next phase, I’m planning on restructuring the flow of Concepts/Concept Exercises to make things feel like more of a “course”. One of the things I’m planning to do as part of this is put the concept exercise introduction more forcefully in front of a student as “now read this” sort of thing. Then they move on to the exercise to put it into practice. Then are refered to the Concept page for more deeper information. So more of a structured flow.

The Concepts themselves will then potentially become more of a reference. And maybe the Concept introduction as a thing is no longer necessary (because we only ever show that page to the student after they’ve done the exercise).

I’m still in the early phases of mulling all this over, so this is a helpful discussion to read to see different perspectives. Thanks both (and future pps!) :) Also - I’ll definitely discuss this on a weekly call soon, so do join for that!