Closed ErikSchierboom closed 3 years ago
/format
So if I summarize things to make sure I understand correctly, we have:
concepts/basics/introduction.md
: Initial description of the concept that students will see before starting it. Should be concise.exercises/concept/lucians-luscious-lasagna/.docs/introduction.md
: The intro description that the student is presented when starting the concept exercise. Should contain more details than concepts/basics/introduction.md
.concepts/basics/about.md
: Summary of concept that students see after completing the exercise. Should at least contain the info in exercises/concept/lucians-luscious-lasagne/.docs/introduction.md
.Is that correct? It's a little weird to me that there is all this juggling between the concepts/
and exercises/
directories.
concepts/basics/introduction.md: Initial description of the concept that students will see before starting it. Should be concise.
Correct.
exercises/concept/lucians-luscious-lasagna/.docs/introduction.md: The intro description that the student is presented when starting the concept exercise. Should contain more details than concepts/basics/introduction.md.
This is not necessarily true. The exercise's introduction could have different information than the concept's introduction, but in the majority of the cases they will be identical. One reason for why they could be different is when you want to rewrite things a bit to better fit the exercise. As the two files will often have the same contents, we will be supporting a template for the exercise's introduction.md file that can refer to the concept's introduction: https://github.com/exercism/v3-docs/blob/master/anatomy/tracks/configlet/generating-documents.md#document-concept-exercises-introductionmd-file
concepts/basics/about.md: Summary of concept that students see after completing the exercise. Should at least contain the info in exercises/concept/lucians-luscious-lasagne/.docs/introduction.md.
This is correct. The about.md
file contains a full exploration of the concept.
Is that correct? It's a little weird to me that there is all this juggling between the concepts/ and exercises/ directories.
Well, it might seem weird from the viewpoint of Exercism v2, but in v3 concepts are separate, stand-alone entities that are viewable outside the context of an exercise. You could consider concepts to be more important than the actual concept exercises, as the latter serve just as the vehicle to teach concepts. Each concept will have its own, dedicated page, and its contents will depend on whether the student has completed the exercise teaching that concept. If so, the about.md
contents are shown, if not, the introduction.md
is shown. There will also be an option to add notes to documents.
We'll also allow linking to concepts, which could e.g. be very convenient for mentors.
Thanks!
Alright, in practice, for our basics concept we end up with 3 identical files but I guess that's mainly because it's the basics one. We might better differentiate those for subsequent concepts.
That's indeed quite likely. One way in which the about.md
of the basics concept will be different from the introduction.md
is that the former can have links. It can also go in a more detail of the concepts, if that makes sense there.
We've recently specified that each concept should have its own
introduction.md
file: https://github.com/exercism/v3-docs/blob/master/anatomy/tracks/concepts.md#file-introductionmd.This PR tries to automatically add these
introduction.md
files for each of the concept of your track. It does that as follows:See https://github.com/exercism/v3/issues/2975