Update concept introductions spec

[ErikSchierboom]

In the evolving spec issue, we proposed a change to the exercise's introduction.md files, namely that each concept that an exercise unlocks should have a section in the exercise's introduction.md file, with its heading matching the concept slug. The goal of this is to display this introductory text when a student views the concept's page without having unlocked the concept (unlocking the concept would result in the concept's about.md file being shown). The introduction text is thus presented outside the context of an exercise.

Since then, as people have started to implement this, there has been some resistance. Specifically the following have frustrated people:

• It is a relatively unelegant solution that requires Markdown parsing and replacing
• Forcing separate sections for each concept might not always be the best way to introduce the concepts for an exercise (although it can be)
• Using other headers can make things look weird
• It's easy to make mistakes. You still never see the final file, and the results are not validatable via CI

We are therefore suggesting some changes to the spec. For those who have already done the work, we will script these changes based on what you've done, so your work so far has not been in vain. The core change is to add an introduction.md document in the concept's documents directory (concepts/<concept>) that already contains about.md and links.json files:

languages
└── <LANG>
    └── concepts
        └── SLUG>
            ├── about.md
            ├── introduction.md
            └── links.json

The goal of this introduction.md document is to be presented stand-alone, without the context of an exercise, and to give a brief introduction to the concept.

Besides solving the above mentioned issues, this approach has the following benefits:

• As the concept's introduction.md document is not necessarily tied to an exercise, it could be subtly different from the exercise-specific introduction, for example by "selling" the concept a bit more.
• All the concept-related documents can be found in the same directory

While the concept description in the exercise's introduction.md may be different to this introduction in the concept directory, we do have to account for the fact that people might just want to include a concept's introduction.md text contents as is in the exercise's introduction.md document. In fact, for today, that is the likely situation for most tracks who don't have time for the extra work. For that it was suggested to use some cross-linking Markdown feature, like the one discussed in this issue. The introduction.md would then look something like this (exact format to be determined):

## Some intro heading

Some text

[[[concept:booleans]]]
[[[concept:conditionals]]]

## Some other heading

Some other text

Basically, we'd have placeholders referring to concepts that would be replaced with the concept's introduction text. Putting these placeholders in the exercise's introduction.md itself does have one big disadvantage: it becomes much harder to see what text is presented to the student. As a maintainer, you'd very likely want to carefully consider the exact text that is presented to the student, so the above is not ideal. To work around this, we're suggesting that exercises that want to refer to concept documentation can use a template file (introduction.tpl.md) that would contain the markdown above, and which we then use to generate the actual introduction.md which also sits in the repository (like how the README.md file of v2 exercises is generated). We'd provide tooling to generate the introduction.md based on the template. This allows you to see the whole file before committing, but also use templating syntax.

The benefit of the above approach are:

• The exercise's introduction.md document still contains the full contents that is displayed to the student
• Exercises that don't want to use the templating approach can simply ignore it

To summarise:

1. Concept introductions will not be extracted from the exercise introduction, but live in the concept folder.
2. Concept introductions may be used within the exercise introduction using a templating system OR a track may choose to have similar content in both varying it based on the context that it is shown.

If the above approach is approved, we'll write a script to automatically generate the concept introduction documents. Each track can indicate if they want to use the templating approach or not, which the script will accommodate. This does depend on the concept headings PR's being merged (7 are still open) and a decision being made on the templating format.

[SaschaMann]

We'd provide tooling to generate the introduction.md based on the template.

Will you also provide tooling to make sure that the introduction.md is always in sync with the source files?

[ErikSchierboom]

Will you also provide tooling to make sure that the introduction.md is always in sync with the source files?

Do you mean checking if regenerating the introduction.md would result in changes (if so, it is not in sync)?

[SaschaMann]

Yes

[ErikSchierboom]

I think that's a totally reasonable feature!

[iHiD]

(cc @exercism/track-maintainers)

[coriolinus]

I like this idea in principle, but I hope that we can resolve one long-standing wart of existing tooling: when markdown files get included, they're copied as-is. This means that the concept exercise introductions would have to use ### as their top-level header, which sort of thing makes my markdown linter very unhappy.

Instead, when including a markdown file, it should be edited in passing to add n levels to every header, where n is the header-level of the current section.

---

It may be worth renaming about.md to reference.md, to more clearly separate the concerns of the files.

[ErikSchierboom]

The new introduction.md file for concepts has been documented in https://github.com/exercism/v3-docs/blob/master/anatomy/tracks/concepts.md