Over the last couple of years, many emails and issues on GitHub requested moving the setup instructions in the Workshop Template to a separate page for valid reasons. To provide some reference, see swcarpentry/DEPRECATED-bc#415, swcarpentry/DEPRECATED-bc#729, swcarpentry/workshop-template#194 and swcarpentry/workshop-template#408.
What did we discover during those years and trials?
Finding the balance to accommodate long time and advanced instructors, novice or intermediate instructors and learners is as hard as carrying a watermelon with a tea spoon. So why are we having this discussion again?
Last year, we changed the Workshop Template by adding some ‘if-clauses’ so that Software Carpentry, Data Carpentry and Library Carpentry instructors could share the same template, see workshop-template#393. In part because of minor differences in how Software Carpentry, Data Carpentry and Library Carpentry lessons and workshops are structured, the ‘if-clauses’ weren’t enough for Data Carpentry and Library Carpentry to use the Workshop Template. With plans to create more lessons in the short future under the umbrella called “The Carpentries”, the urge to move the setup instructions has reappeared and we need to nail it.
I put a prototype in place,
that demonstrates how we can require the lead instructor
to only list within the Workshop Template
index.html’s YAML header the lessons that will be used during the workshop
The proposal idea has as advantages:
- reduction in the number of lines that need to be edited in the workshop page, that is, 3-5 lines in the YAML header instead of many open/close comments;
- reduction of confusion where the files with instructions to install a given software can be found, as all instructions are in the lesson that will be taught;
- avoid the ugly and hard to deal with
<iframe>size can’t be responsive;
- reduction in the amount of time to propagate some important changes, e.g. that learners can’t use Firefox Quantum because the SQLite3 add-on isn’t compatible.
Some drawbacks will happen:
- one-time customizations will require more work, basically to clone a repository to customize the installation instructions;
- increase of page load/rendering time (I’m talking about much less than 1 second).
The drawbacks are minimal compared with the advantages.
This post is only the start of the conversation. All comments are welcome in swcarpentry/workshop-template#459. No change will be made without a technical and rolling plan consensus.