config.json duplicates information from problems.md

[petertseng]

After the merging of #229, problems.md now duplicates config.json in both problem order (it was already duplicating it in this regard) and topics (added). So, what should we do about this duplication?

There are two pieces of information in problems.md that are not present in config.json

1. Background including links to posts explaining why we order the problems as we do.
2. Section headers

## Introduction

The first section contains the sort of stuff you expect when learning any programming languages: conditionals, booleans, looping and some higher-order functions.

Option 1: We could do something really silly like "the first (not ALL, that is duplication) problem of a section gets a section_name and a section_description", like this:

    {
      "slug": "hello-world",
      "difficulty": 1,
      "section_name": "Introduction",
      "section_description": "The first section contains the sort of stuff you expect when learning any programming languages: conditionals, booleans, looping and some higher-order functions.",
      "topics": [
        "Some/None",
        "println!"
      ]
    },
   {
      "slug": "gigasecond",
      "difficulty": 1,
      "topics": [
        "crates",
        "math"
      ]
    }

(and so on)

Option 2: Keep the problem order duplicated in problems.md along with keeping the section headers there, but remove all topics from it, pointing to config.json as the authoritative source for the topics?

Option 3: Remove problems.md completely, losing our section headers and background.

Option 4: Keep problems.md as-is, accepting the duplication of topics.

Please also provide alternative options, if you have any.

I find option 4 completely unacceptable, but can be convinced of the other three options. My leading option is 1. This means I might execute option 1 at a time convenient to me if nobody provides a better alternative before that time (since there has been time to ponder over this while considering #229)

[ijanos]

Here another idea: what if we create another markup file (eg: sections.json) that contains headers, descriptions and add a "section" key to every problem in config.json and then create problems.md automatically based on the two files if we want a human readable version.

Otherwise I would choose option 2. Option 1 is way too hackish for me and I think it would be hard to maintain that file to someone who does not read this issue.

[petertseng]

Ah, automatically generating based on config.json and the other file seems OK.

Would you propose that we keep the generated problems.md in the repo (as a matter of convenience), or not (as a matter of not committing generated files)?

(If yes, I might even suggest a CI check that the generated file matches the inputs, in case someone changes the inputs then forgets to regen)

As a small optimisation: If we assume that we do not jump between sections, we may simply add one "section" key to the first problem of a section in config.json? Or maybe a "starts_at": "hello-world" (for example) in sections.json?

[ijanos]

Keeping generated files in the repo is not a great solution but I can live with that. I'm not familiar with the file, who is using it mainly? If it is for maintainers only then I guess we can update and commit it every once in a while and do not sweat too much about it being a little outdated, adding a CI check is probably overkill.

About keeping only one key per section in config.json: I don't think such a small de-duplication worth it, I prefer to keep problem metadata self-contained. With your proposal I have to look up a problem and then scroll around in the file to find the matching section data. And new contributors might not notice that by placing a new problem in the json will implicitly place it in a section, if we add a section key to every problem we make the section choosing an explicit thing that people will think about.

[ijanos]

Just a thought: are there any other tracks with a similar problem? What do they do?

[petertseng]

I'm not familiar with the file, who is using it mainly? If it is for maintainers only then I guess we can update and commit it every once in a while and do not sweat too much about it being a little outdated

Here's my take, but feel free to correct me Ian. It helps us decide where to place a new problem, so it can be useful for maintainers and any contributors who wish to add a problem. It can additionally be helpful for anyone else who wishes to know why problems are ordered in the way they are (is there anyone in this set of people outside of maintainers and contributors?).

I prefer to keep problem metadata self-contained. With your proposal I have to look up a problem and then scroll around in the file to find the matching section data.
if we add a section key to every problem we make the section choosing an explicit thing that people will think about.

OK, I'm convinced.

are there any other tracks with a similar problem?

Well... all tracks share the problem of "how do we order our exercises", but I'm not sure any of them have gone as far as to make the problems.md file and segregate the exercises into various sections.

The history of this file is from #167 and #127 - in fact, you could consider problems.md the predecessor to having topics, as seen in exercism/discussions#60 .

So I guess now we're just figuring out what to do with this predecessor now that the topics concept is available to other Exercism tracks. Still don't necessarily have a good answer to the sections concept.

[IanWhitney]

Here's my take, but feel free to correct me Ian. It helps us decide where to place a new problem, so it can be useful for maintainers and any contributors who wish to add a problem. It can additionally be helpful for anyone else who wishes to know why problems are ordered in the way they are (is there anyone in this set of people outside of maintainers and contributors?).

Yes. It is largely for maintainers and any one else with an interest in that sort of thing. I like the idea of us explicitly saying "This is why we order problems the way we do". However, I think a document can state the reasoning behind our thought without explicitly listing each exercise.

So, if we just kept the prose parts of problems.md as a statement of our values, everything else can move into the json file.