Consolidating Installation Instructions for SWC lessons

[fmichonneau]

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:

1. installation instructions only live on the lesson pages, the workshop template will include links that point to these instructions.
   • pros:
     • easier for maintainers to keep installation instructions up to date
   • cons:
     • workshop participants need to open up many websites to follow along with installation instructions for their workshop
     • workshops that use custom installation instructions will most likely still need to provide installation instructions in 2 places (workshop-specific, and general)
2. installation instructions only live on the workshop template, the setup page of the lesson point to the section on the workshop template
   • pros:
     • better experience for the workshop participants when they use the website for their workshops
   • cons:
     • easy for installation instructions to get out of sync with the lessons
     • the rendered version of the workshop website at https://carpentries.github.io/workshop-template include FIXMEs 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).
3. installation instructions are synchronized on the lesson and the workshop template using a GitHub Action, for instance file-sync. The "canonical" installation instructions would live in each lesson repository (in a file in _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.
   • pros:
     • evens out the pros and cons of the other 2 solutions
   • cons:
     • more complicated setup for lesson maintainers to manage and creates more points of failure
     • potentially confusing for contributors that pull requests for installation instructions can only be made from the lesson repositories and not the workshop template.

Timeline

Please comment on this proposal by Tuesday, 3 November end of the day everywhere on Earth.

[sstevens2]

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).

[ChristinaLK]

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?

[annajiat]

I would like to vote for option 3.

• We may need to provide common but separate instructions for installation and data file downloads first.
• Then we may choose to add optional sections on lesson-specific additional content for both the installation part and data file downloads.
• We may choose to decouple instructions for software installation, configuration, and data file downloads
• There are multiple stakeholders: lesson maintainers, lesson contributors, instructors, learners, etc. We have to be aware of all viewpoints. Should we have a themed community discussion on this?
• Even though each lesson may have instructions for software installation, configuration, and data file downloads, we may choose to automatically maintain an aggregate version as well. It may serve at least two purposes:
  -- It may be interesting to look at all variations at a glance: common parts and lesson specific parts. It might be easier to have overall observation on how lessons are branching out, organization, recommendations, etc.
  -- If some instruction become common to all lessons, it will be easier to notice and then it may be moved out of specific lessons may be and then put to a common location.

[maxim-belkin]

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.

[gcapes]

1 or 3. Think about the non-core lessons like Make and MATLAB. Their installation instructions are not on the workshop template.

[LucaDiStasio]

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).

[vahtras]

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.

[ACharbonneau]

3. In a similarly large complicated project I've set up a lot of github actions to manage things. The startup to get them running the way you want is larger than the other options, but once they're done, they're pretty reliable and mostly fall into the background. As long as there are very clear instructions for how and where to make changes, we haven't had too many issues with confusion or more difficultly working with the repo. All of the difficulty I've had with setup has been around security issues: default secrets can't spawn multiple connected actions, so you need to set up a secret with more permissions...but then its tied to a single user who needs to set it up on all the repos...etc. But that might be where 'organization secrets' become useful? I haven't tried those yet.

[Teebusch]

1. for its simplicity. I believe learners are able to follow one link, from the workshop page to the lesson page, without getting lost or confused. Duplicating information in different places can itself also be confusing. It may be better to have one dedicated place for it.

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.

[bkmgit]

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.

[n2ygk]

+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.

[kekoziar]

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.

[kekoziar]

My vote is for option 2, one place on the workshop template.

• it's the option with the least points of failure
• the FIXME concern under the cons no longer exists
• we should design for learners, and reduce the cognitive load for them - many of them already doubt if they can learn to code, and installation is one of the larger issues. Why make it more confusing for them?