Open fmichonneau opened 4 years ago
I'm for 3 or 1 in that order. I'm not completely sure of all the possible pitfalls with 3 but it seems like a good compromise that keeps the install directions closely connected with the lessons and makes them available for folks more easily when they install using the workshop website. It isn't ideal to have to go to each lesson page to install but I'd prefer that to having the lessons point to the template, which isn't the first place most folks would look when looking for install directions. It would also be confusing for folks who work through the lessons on their own if they go to the setup page and are pointed to the website template (which is a very back end facing page).
I agree with Sarah. I think it's important that the lessons be "stand-alone" because they can be used outside of the official Carpentries workshop setting. I don't see any major downsides to 3, unless it makes the workshop template unwieldy to use.
One clarification re: option three -- would we sync JUST the tool installation or also the data download required for that lesson?
I would like to vote for option 3.
Option 2 will cause a lot of confusion for contributors wishing to update lesson setup instructions. Options 1 and 3 are both viable.
Option 3 prefers core lessons over incubator/custom lessons but has the advantage of showing all instructions (for core lessons) on a single page but I wonder if that's really so important.
Option 1 requires less work, does not rely on GH Actions and makes core and incubator/custom lesson equal. Its downside is that instructions won't be on a single page but I think we can (and, perhaps, should) rely on people being able to navigate webpages back and forth.
1 or 3. Think about the non-core lessons like Make and MATLAB. Their installation instructions are not on the workshop template.
I vote for option 3.
Pre-workshop setup is often one of the hardest steps for participants, especially novices. Thus we should aim to provide the info as clearly and as simply as possible. Workshop participants receive the link to the workshop website, not to the lesson pages. Option 1 would thus leave installation instructions too many clicks away from where they arrive the first time they click on the link provided. Not a good user-experience to begin with.
However, lesson pages are publicly accessible as they are meant to be a self-study tool for whoever finds them useful, at least (hopefully) participants after workshops and people in their circle through word-of-mouth. These users on the other hand are likely to arrive directly at the main lesson page shared during the workshop, at the main lesson page through the Carpentries website, or at some page of the lesson through a Google search. Thus installation instructions should live somewhere in the lesson pages so that these users can find them a few clicks away from where they arrive.
Option 3 answers both concerns. I agree that it puts an additional load on maintainers, but some preventive actions could decrease it. We could for example state in Contribution guidelines where and how installation instructions might be edited, and that pull requests relating to Contribution guidelines in the wrong repo will be automatically closed. Maybe this could even be automated with a Github action (not sure though).
Lessons should be as self-contained as possible. Sound like 3 is a good option, I am not sure about all that it means for maintainers, but it should be doable.
anyways, 3. would also be acceptable, as long as the setup process for the workshop site doesn't get more complicated than it already is.
Having the setup for each lesson within the lesson seems easier to manage. The new templates have locations for installation instructions, so these can be linked to from the workshop website. Workshop websites can probably be configured to point to the setup information for the lessons being taught. Though this requires some effort.
+1 for option 3. We have always had to customize our workshop template to emphasize the need to download the data files in addition to the software so anything that can help unify the to do list in one page would be helpful.
Having the setup for each lesson within the lesson seems easier to manage. The new templates have locations for installation instructions, so these can be linked to from the workshop website. Workshop websites can probably be configured to point to the setup information for the lessons being taught. Though this requires some effort.
Referencing issue originally opened in git-novice repo, where @zkamvar also commented on the feasibility of moving setup instructions to individual lessons.
My vote is for option 2, one place on the workshop template.
Following #4, we've simplified how instructors can customize the installation instructions for their workshop websites by re-organizing how these instructions are stored in the repository.
However, the issue of having installation instructions on both the lessons and the workshop template remains.
There are a few solutions that we can think of:
FIXME
s and doesn't look like a website that should have canonical versions of the installation instructions (this mostly applies to people who would get to this page by following the lesson setup instructions, that's what the Git lesson currently does for instance)._includes
so the instructions are by themselves). On schedule (once a day), the action would bring the content of the setup instructions to the workshop template repository for each lesson, and they could conditionally (with the template depending on the content of the workshop specified in the_config.yml
file) or manually be included on the workshop website.Timeline
Please comment on this proposal by Tuesday, 3 November end of the day everywhere on Earth.