Structuring topics

[iHiD]

One of the learnings that came out of the Reboot process is that helping students find the right exercises to work on is a critical part of making Exercism enjoyable, reducing the barrier and time to learning, and reducing frustration. There are three axes we are initially doing this on: difficulty, average time to completion, and topics.

As such, topics will appear around the site in lots of places. For example in the following two images you can see topic percentage completion on a track and topics on an exercise card. Integrating topics into the site in this way means there are certain "design rules" that we need to follow to make them look good. This means, for example, not having topics that have more than X characters in order to fit them on a line.

There's also other nice stuff that we'd like to be able to do with topics such as analysing coverage across tracks and looking at cross-corrolations with difficulty, length, completion %, etc. This sort of data might be able to help us find the strengths and weaknesses in each track and help us work out what sort of exercises we could do with adding where.

This leaves me with two linked considerations:

1) We need guaranteed consistency within track

To guarantee constancy I would like to propose that topic names listed in the config.json should be underscored lowercase alphabetic (e.g.control_flows_if_else). This makes them easy to visually scan and allows us to more easily notice differences that when comparing more natural language strings. e.g. "Control Flow (if / else)" and "Control Flow (if | else)". This also allows us maintainers to structure these topic names in a way that makes sense to them but that might not naturally make sense to a student (e.g. the use of the phrase "control flow" is useful for experienced programmers but scary and confusing for beginners who might be better just seeing "if / else")

2) Display names in the UI will want to be pretty and flexible

For example, we might want to put a unicode character in the UI, but we wouldn't want that in the neat underscored track data in config.json. We might also want to rename all "If / else" to "If and else" or "If | else" without having to update the config.json data everywhere. We therefore need a mapping between the topic names that appear next to exercises in the config and the UI versions. We don't want to shoehorn tracks into following certain topics where that's not natural - languages are different - but where there is overlap, we want to utilize it where possible.

Suggestions

After some brief thought I think this could be in three places:

a) As a separate array in the config.json, so the exercises.topics are keys pointing to the topics array. This doesn't help us with cross-track consistency, but will be good for ensuring track consistency.
b) As an array in a global cross-track config file, which enables us to guarantee consistency. This strikes me as great in theory, but a big pain for adding new topics.
c) In the UI database and managed by the UI team, not the track maintainer. New topics that hadn't been seen before would be "titliezed" so "control_flow_if_else" would become "Control Flow If Else" in the UI, and would be flagged to be checked by the UI team, who could then enforce whatever rules they want.

I'm edging towards (c). If we did this then I'd happily go through all the topics across all the tracks so far and write an initial mapping and put PRs out to update the existing configs.

This still leaves me with the question about consistency across tracks, but I wonder if that's just something that we periodically review, rather than having a formal process for.

As a side note, there's an existing file here which contains a set of the current topics in use. I'm not sure how comprehensive or up to date it is.

I'd value everyone's thoughts. (cc @exercism/track-maintainers)

[rpottsoh]

As a side note, there's an existing file here which contains a set of the current topics in use. I'm not sure how comprehensive or up to date it is.

I refer to it. Looks like the file is 11 months old and was last updated in January. Would this file be updated by replacing spaces with underscores?

[iHiD]

Would this file be updated by replacing spaces with underscores?

I would suggest:

1. Updating this file with underscores and the UI versions. Keeping it as point of reference showing that mapping in a visually useful way. Programmatically updating it whenever changes are made on the website (ie new config.json changes are read in or the UI names of tracks are changes).
2. Generating PRs for all tracks that update the topics with the underscored versions.

[tleen]

While on the topic of topic consistency going to link in exercism/problem-specifications#820.

[ErikSchierboom]

Updating this file with underscores and the UI versions.

+1

[rchavarria]

I'd like to see cross-track consistency on topics used. That would help a lot to UI to show consistent topics across different languages.

It looks a good idea to have topics internally managed as lowercase with underscores (control_flows_if_else) while that value could be translated in the UI. So control_flows_if_else will be Control flows (if-else) or Control Flow (if/else).

So far, as a track maintainer, I've been using exercism/problem-specifications#820 as the source of truth for topics. It can be that file or any other file. But, I'd like to have a list of topics, shared by all tracks, that will help us to get cross-track consistency easier.

[ErikSchierboom]

Maybe we should restructure the existing file to be a set of key/value pairs. Something like this:

{ 
    "control_flows_if_else": "Control flows (if-else)",
    "regular_expressions": "Regular expressions",
    ...
}

This mostly depends on if we want to use the topics.txt (or topics.config/topics.json) file as the source for the UI display of the topics. If we want to do that, the key/value pair makes sense. If you don't want to do that, perhaps just having an array of normalized topics would suffice:

[
    "control_flows_if_else",
    "regular_expressions",
    ...
]

Another thing to consider is if the topics themselves should have some sort of metadata. One could for example "link" similar topics, such that when you are working on an exercise that has the "lists" topic, it could suggest an exercise with the "queues" topic.

[iHiD]

Thanks for feedback so far :)

My thinking is that the database should be the single source of truth, and that that file should be auto-generated every time the database topics are updated (either because of an update to a track's config.json or because a topic name has been changed in the db).

I think the file format itself should be whatever the maintainers are going to find easiest to use. It could be a markdown file or a json file, could be organised alphabetically or by most popular topic. I don't really have an opinion on this as I won't be consuming it, but think the key is that it makes maintainers lives easier where possible.

Another thing to consider is if the topics themselves should have some sort of metadata. One could for example "link" similar topics, such that when you are working on an exercise that has the "lists" topic, it could suggest an exercise with the "queues" topic.

This is a really great idea. Again, I suspect the right place for this should be in the db, where the full picture is clearest, and we can algorithmically generate some of this stuff.

[rchavarria]

Sorry for asking, but I don't know what is the database @iHiD is talking about (where to find it,...).

It's not a big deal for me, as long as we have a text (txt, json) representation of topics in that database (that's a lovely idea). I think a small gap in the synchronization is manageable (they don't have to be synchronized every millisecond).

[iHiD]

@rchavarria - Sorry. I mean the main database of the website. At the moment a new version is under development as part of nextercism.

[rchavarria]

@iHiD - yep, I thought it was more or less that. So, it would be very nice to have the text representation of the topics. I don't expect it to be done right now, from my side, I can work with the list of topics we have on TOPICS.txt.

I'll be listening to this converstation.

[rbasso]

I feel that cross-track consistency of topics isn't something we should pursue, because concepts with similar names have distinct meanings across languages, and similar concepts have different names:

• Maps and folds have different names in different languages. How would we call them?
• Which name should we use to describe parametric polymorphism? Will it be easily understood by users of all languages?
  • Templates?
  • Generics?
  • Type variables?
• ByteString, String and Text in Haskell are all sequences over an alphabet, but the name String is only used for a list of characters. I guess that in R it would be a character type, which may have zero of more characters, while other languages consider a Char or char to be exactly one.

What I'm trying to make clear with those unfortunate examples is that each language has its own vocabulary! A set of topics common to multiple language would feel alien to most of them, and that would just confuse the users.

Also, track-specific topics allow tracks to be more self-contained.

[ErikSchierboom]

A set of topics common to multiple language would feel alien to most of them, and that would just confuse the users. [emphasis mine]

I would argue that your statement is too harsh, I don't think many topics would be alien to most of them. While certainly true for some topics (the strings are a good example), it won't be true for a lot of other topics. For example, the topics "Booleans", "Sorting", "Abstract classes", "Bitwise operations" are likely similar enough across languages to allow them to be used across the board.

It is interesting to note that when I created the "TOPICS.txt" file, I intended it as a starting point. If the desired topic wasn't there, you could add your own. I do agree that there should be some way for individual language tracks to define their own topics, as it is quite possible that a topic is unique to a language. Maybe each language track should be able to define their unique topics in the config.json file?