kytrinyx
commented
2 years ago This is great, thank you!
I'll open a draft PR as a starting point for discussion, and then we can ask the various folks who have experience to take a look.
From there we can merge and then get feedback from the folks who are in the process of creating a syllabus, since they'll invariably have questions that help flesh it out.
It feels like quite some maintainers/contributors are interested in creating a syllabus for their track but don't really know where/how to start. Would be good to have some info about hat.
I will paste some of the thoughts I mentioned on Slack below in case they will help with creating the docs page.
Thoughts around syllabus creation
#### Think of concepts in layers What helped me sorting out the unlocking mechanisms/ desired order of the concepts in the tree was thinking about them in layers/batches (kind of horizontal sections in the concept tree). For example for Go and JavaScript the first layer way about the basic primitive types (strings, booleans, numbers with 1 exercise each). Then I thought about what concepts can be unlocked with those and that formed the next layer. In this case it was arrays, comparison and conditionals which formed layer 2. For and while loops couldn't be in layer 2 because they depend on understanding comparison/conditionals so they needed to go into the next layer (3) etc. #### Collect some basic info about the exercises/concepts in a structured format - As an intermediate step between just a list of ~20 concept names and the GitHub issues about creating the new concept/exercise for contributors to work on, I can recommend to write down some info per concept in a structured format. For example: ``` Exercise 1 [name can be inserted here later on if the story is decided upon] - Concept(s): [slugs of the concept or concepts that the exercise should teach] - Content: [very short description of what should be taught] - Out of scope: [optional in case there is something that is already known to be excluded] - Prerequisite Concepts: [which of the concepts from other exercises above are strictly needed to understand the concept(s) in this exercise] - Exercise Idea: [link to an existing exercise that could be ported/adapted here or some new story idea] - Status: [e.g. have a checkbox whether the GitHub issue was created or not] ``` - Would be good to collect this in some tool that allows multiple people to edit like Google Docs. If this is done via a GitHub issue description, make sure all people involved in the syllabus design can edit the description. Having just one person that can edit and others with same "authority" over the topic only posting proposed changes in comments below usually did not work out very well/ lead to big overhead for the person with edit rights. - Sort the exercise/concept list so that an exercise only depends on concepts taught by exercises above. Of course there is the tree/layers shape mentioned above but writing things out linearly ensures that at least there is one working unlocking path through the syllabus. - Take some time to ponder and iterate that list of exercises so it looks like it could work out before writing out all the details needed for the actual GitHub issues per exercise. #### Handwaving is sometimes necessary This part is for when it feels like there is a deadlock, concept A requires understanding concept B, and B requires understanding A (or more complex versions of that). To get a sensible syllabus and unlocking, it is not always possible to explain everything 100% correct/in detail. Sometimes it is necessary to hand wave over some aspect and then give a more thorough explanation at some later point in the syllabus. For example in Go we needed to introduce functions rather early so students understand multiple return values because they were needed for other concepts. However, to fully understand "pass by value/ pass by reference" someone would need a good understand of pointers. Teaching pointers needed some more concepts that came after functions. So in functions, we waved over the pointers thing a bit and said it will be introduced in more details later. That way we could get functions done and leave pointers for later when the student is a bit further into the track and knows all the things we need to properly teach pointers. #### Don't feel obligated to put concepts in just because other tracks have them For example Go has no enums and JavaScript has no string formatting. There was some discussion whether those concept names should nevertheless show up in the concept tree and then describe what to do instead. But in the end we decided against that. I feel the concept tree should really represent the concepts that exist in the language. So in Go, we now want to do the "constants" concepts which will then explain the patterns how constants are used as workarounds for the missing enums. #### How to proceed after a long-list of future concepts was created 1. If it does not exist yet, it would be good to select the first 10-15 concepts that will constitute the top of the concept tree. The concepts mentioned on the exercise posts above might help choosing those. Maybe the tree will look the same as this one https://exercism.org/tracks/fsharp/concepts, I can't judge that. 2. For each of those 10 concepts, make some notes about what should be covered and what should be out-of-scope and which concepts it depends on. (I wrote about the "template" I used for this in the markdown I shared above.) 3. Once those notes are ready, GitHub issues about writing the concept and exercise can be created. Ideally this will enable other contributors besides the people in this channel to help with the effort. I will share some examples how these issues look like in other tracks below. If people are confident about the order and scope of the concepts defined in step 1, it is also fine to skip step 2 of course. #### Issue Templates Example issue for creating concept + exercise: https://github.com/exercism/go/issues/2037 Bethany from the Python track started to separate concept and exercise because both together are often too much work for one contributor. Concept: https://github.com/exercism/python/issues/3106 Exercise: https://github.com/exercism/python/issues/3105 #### How to select the first concepts From @kytrinyx: Select 5 simple practice exercises in the track and note down the concepts that a student needs to know about to solve those. Those should constitute the upper part of the concept tree.