Summary of May 30, 2025 planning meeting #5
Description
A planning meeting about strategies for managing the snippets and configuration variables for this repo was held on May 30, and reached some decisions, and talked through some issues without full resolution.
The customization scheme has two major pieces, configuration variables controlled by the episodes/lesson_config.yaml file, and snippets contained in files in subdirectories under episdoes/files/snippets/<your-site-specific-dir>. The plan is to retain this structure.
For config variables, we decided we should rename the lesson_config.yaml file, since it's easy to get it confused with the top-level config.yaml file. We haven't settled on a name, but something that reflects its role would be good, like site_config.yaml or something.
This file is loaded by a bit of R code, which means we don't have to use a fixed name. So the plan going forward for config variable localization is that each site should write their own site-specific yaml file, with their site added to the descriptive name (like maybe ctcms-site-config.yaml, or equivalent). We can set an environment variable at build-time via the CI so that the correct file is selected and rendered -- we own the R code, so we can have it interrogate the environment to learn the name. We could also have hierarchical config files, but this is not currently the plan.
The default config will be the Magic Castle one.
For snippets, it was observed that a lot of the existing site snippets in the old Jekyll version are near-duplicates of each other, and that a few sites are using snippets for descriptive text that may be site-specific, but also is often just an elaboration on the point made in the base lesson. In both cases, snippets feel like the wrong channel. Duplicated text should instead maybe be in the main lesson or in a default snippet, and content elaboration that a site has found useful should be contributed back to the main lesson as a PR.
Some sites have over-localized -- CTCMS is one of these, we have a snippet with our sinfo output, for example, but actually it was probably obsolete soon after it was written, because nodes and partitions come and go. The solution for this and many others is that the base lesson should have representative output, and during an actual workshop, learners will see in real time what the actual system does, along with the instructor, so it's not a case where representative text in the base lesson imposes a cognitive burden on instructors or learners.
So, the plan is that we should de-duplicate and pare down the snippets as much as possible, and try to build a lesson culture where snippetization is reserved for cases where it adds significant value.
Which use cases those might be was a subject of some discussion, and is still unresolved. Some folks want to put hooks in the episodes at the start and end to allow for arbitrary snippets, but were not able to convince everyone that this was a good idea. An argument was made that this allows deeper dives on e.g. site-specific file system uses, which is a good example, and that it adds value to self-paced learning outside of a workshop setting, which is in tension with the role of the lesson as primarily the basis for workshops.
The plan going forward is to reach out again to some of the maintainers of the forks, and solicit feedback on their opinions about the value of flexibility in adding content and making adoption easier vs. the value of merging good new ideas upstream for the benefit of the broader community.