So we have the concept ‘introduction’ and the concept ‘about’, and we have the concept ‘exercise introduction’.
Do we have any metrics about how often these three things are viewed, relative to each other?
It is my understanding that the user does not see the concept ‘about’ until after they complete the concept exercise. I might be wrong about this.
My practice is that all three documents are the same. I assume that once a typical student finishes the exercise, they’re not going back to re-read the docs, so I might as well show them everything up front.
One situation where the concept’s introduction.md and the exercise’s introduction.md might be different is when the exercise is shared with other concept.
Also, many concepts I’ve checked, in different tracks, do indeed copy-paste between about.md and introduction.md, but this is not always the case.
In x86-64-assembly, I’ve tried to make the docs the same, but this is mostly because the introduction.md is already large enough.
My experience as a student is that I usually go back to a concept after finishing its exercise. This is very common while I’m doing a practice exercise just after finishing the concept. The concept is my first reference, before searching somewhere else.
This is something that Jeremy has expressed (very) strong opinions about: to some extent in the docs, more vigorously in past community calls.
I aim for these principles:
The Exercise introduction.md should (pretty much) only contain material needed for the concept exercise, and few if any external links.
The Concept about.md can be long and detailed, with copious links. This is especially true for languages with documentation that is either sparse (many newer languages) or beginner-unfriendly (Julia, notoriously).
The Concept introduction.md is usually the same as the Exercise version, maybe slightly longer.
So the introduction.md is for solving the exercise, the about.md is a lasting reference to come back to in future. Following past guidance from @BethanyG, I write the About first, then chop it down for the Intro.
I worry that many (most?) students don’t even know about the About, and never think to look at it. I console myself with the thought that the detailed About docs are useful to me, and I write them at least partly for my own use…
OTOH, writing a syllabus is hard, and anyone willing to see it through to the end deserves to be given some flexibility to do it in their own way!
In general: introduction.md between exercise and concept will be the same or similar, but about.md will always have more information when possible. Usually specific stuff that doesn’t make sense to introduce.
I also try to link back to older concepts (with the “concept link include thing” that could later be displayed differently).
I’d also be interested in usage statistics of the 3 documents, as I also did not go back to the concept docs after doing the exercises. And I don’t think many students (especially younger ones) go back.
Anyways, in PHP track we use the introduction.md.tpl method of automated copy&paste from the concept to the exercise. So we only maintain one short and one long form (which often is no longer, either).
I like @colinleach method, build the about.md first and then clean it out for the introduction.md. When building the draft for the Odin track Basics concept I went the other way and it is definitively harder to add explanations than to subtract it.
I am torn with the introduction.md for the exercise. I tried to make it simpler than the introduction.md for the concept but then I already wrote the concept introduction to be minimum so there was not much to remove.
The other problem that I have is maintenance. I ended up with three versions (levels) of the same document. So when somebody suggested a change to one of the explanation, I had to go back to the three documents and make some changes. Before long I had divergent documents explaining the same idea in slightly different ways. Which also create the risk that you may say two different (potentially conflicting) things to the student depending where he looks.
To me consistency is the main argument towards having the exercise introduction being a copy (template) of the concept introduction. Plus if you are in the Exercism UI working on the exercise, you have access to the exercise introduction right there, no context switch required.
I am thinking that an approach where you write a single document (the about.md which is the more detailed) with some special markup indicating which sections should be removed for the introduction.md and then use a simple script to generate the three files would make it easier to maintain good explanations in the long run and keep the documents consistent with each other.
@colinleach, which track did you work the syllabus for? I am interested in taking a look at your approach.
I previously worked with @BethanyG to extend the Python syllabus, and she taught me a lot. More recently, I made a start on a Kotlin syllabus, working with @SleeplessByte (who previously built the JS syllabus). Unfortunately, that’s stalled at the moment while I work through some health issues, but I hope to get back to it asap.
We learn from each other and try to keep improving. Elixir was an early example of a really good learning syllabus, so a lot of other tracks copied ideas from that. Much of this collective wisdom is summarized in the Exercism docs, so reading those can save you a lot of pain later.
One thing I learned from the Kotlin team, which I wish I’d known while writing Julia stuff, relates to reference links in the Markdown. You can do this, so that all links are gathered at the end and can be referred to from multiple points in the document:
Strings are in [Unicode][unicode].
[unicode]: https://en.wikipedia.org/wiki/Unicode
It’s better to add a prefix making the type of link obvious.
wiki-unicode in this case, for Wikipedia entries.
ref-unicode for your language’s official manual.
web-unicode for other sources around the internet.
concept-unicode for cross-links to other concepts within your Exercism syllabus.
IIRC, the About.md is also displayed for exercises that the student has yet to start. For SEO purposes as well as the student needing good info about what they’re getting into.
I do remember longer discussions, but can’t find them at the moment.
This is excellent, and I can’t believe that I’ve gone this long without doing that in Python! Well, another thing to add to the list…
Thank you, I will go look at the Julia and Exercism concept documentation. I read through the Exercism Docs concept and concept exercises but my brain works better when looking at examples, I will get back and get another read though.
