install instructions no longer rendered by default

[munkm]

The git install instructions used to be rendered in the default workshop template (at https://carpentries.github.io/workshop-template/#git ).

The git-novice lesson references this page for setup with git so we don't maintain git install directions in the git lesson directly. As brought up in swcarpentry/git-novice#735, the git installation instructions are no longer on that page. I assume it's from f8862b, which changes the default from swc to cp. What would be the best path forward for linking to rendered installation instructions for our learners?

[brownsarahm]

I think relying on the rendered version of the template repo is not ideal, so it might be best to move the setup instructions to the git lesson repo, and then have this repo switch to linking. That's the pattern already used for DC and is proposed for LC & SWC in this maintainer RFC.

Since that RFC is not agreed on as the path forward yet, maybe we revert the commit you mentioned, which would make the instructions render here again until that's resolved. For community reasons I prefer having cp be the default; swc as the default as that makes it seem like swc is preferred in a sense over dc and lc.

@ErinBecker & @fmichonneau what's the path to resolving the RFC?

[maxim-belkin]

In Install Python section of the Python Novice Inflammation lesson we point readers to https://carpentries.github.io/workshop-template/#python page for instructions on how to install Python. We can, of course, duplicate that part but this will inevitably lead to diverging instructions down the road.

I suggest that when carpentry is set to "cp", setup instructions for all Carpentries are shown, either on different pages or on a single page using the some smart Javascript that currently let's people select instructions for different operating systems.

[sstevens2]

Ideally, it would be nice if the instructions lived in the individual lessons and we had an automated way to pull them from the lessons into the workshop template, so they don't diverge. Not sure how/if that is possible though.

I agree the duplication is not great but I think it is long term better to have them in the individual lesson repos instead of pointing folks to the workshop template. I suspect that users may find the workshop template a bit confusing and I think the redirect from the lesson to the template might be a bit disorienting.

[brownsarahm]

The risk of diverging instructions already exists with the datacarpentry setups for R and python being pushed to individual lessons, since we link out there?

For mainenance reasons, a centralized copy makes sense, but the trick is to figure out where that centralized copy lives.

Maybe the centralized copy goes styles/ carpentries theme as an include and the setup.md in each lesson can either use those includes for standard parts or maintain their own instructions as needed for custom?

[ErinBecker]

Good discussion all. Yes there is a risk of diverging install instructions if the instructions live in the individual lessons, but that's actually fine, from my perspective. Different lessons teaching the same technology may still have different prefered setup. Just a couple of examples:

• R lessons focusing on tidyverse vs base R
• Python lessons using different visualization libraries
• Git lessons targeted at different levels of learner expertise (e.g. using command line vs a desktop GUI)

Having the install instructions live in the template made a lot of sense when there were only a couple of different possible workshops (e.g. SWC with R or SWC with Python). We now have something like 10-12 different "official" workshop curricula with their own install requirements, and several other unofficial curricula combinations that are taught at self-organized workshops.

I'm strongly in favor of moving install instructions to the lessons and linking to them from the workshop website template based on the curriculum and flavor variables.

[brownsarahm]

Erin's additional information pushes me more to the side of separate instructions living in each lesson repo.

Maybe supported with some sort of dedicated communication channel that connects all maintainers of lessons of the same "flavor" across curricula & lesson programs to share when an update related to changes in the tool to help support all staying up to date & minimize replicated human effort even though text will be repeated across repos?

[munkm]

Ok, so some of this seems like larger infrastructural stuff that needs to be implemented. Is what @maxim-belkin proposed where all setup instructions are shown in the 'cp' template a good interim solution? Right now we're linking to the raw html setup document in git-novice, and I think it's fairly unwelcoming to novices to expect them to read through raw html to do their setup this way.

I also wonder what it would be like for a new learner to click through each lesson to do the setup for a workshop. Our original way of doing it had all of the setup instructions available on the workshop page--rendered on the workshop page--conveniently putting everything in one place for them to prepare for the workshop. If all of the setup instructions live in each lesson and then learners need to click to each lesson to complete the setup for the workshop, that's adding more for the learners themselves to do to set up for the workshop. I worry that that could be intimidating for some learners. Is there some magic way to have the setup directions live in each lesson repo and then based on what lessons are used in each workshop those directions would be rendered in the workshop page directly? This could maybe work with submodules somehow, but that also seems like a lot of burden to add to the maintainers.

[munkm]

I've modified the title now since the install instructions include other lessons as well, and not just git

[ErinBecker]

Note:

We're reverting the default from "cp" back to "swc" for the moment. That should serve as an immediate bandaid. I'm going to be working on a Google Doc to outline a longer term solution. I'm just getting it started, but please feel free to jump on at any point. I'll be working on this actively over the next couple of hours and then will be discussing with the Curriculum Team (@zkamvar @fmichonneau) on Tuesday.

[kekoziar]

I agree with @munkm that "it's fairly unwelcoming to novices to expect them to read through raw html to do their setup this way" and think it's easier on new learners to have the install directions live on the workshop page.

@maxim-belkin has made suggestions before on automating and prepopulating the schedule and other parts of the workshop page based on flavors (I think that's the term used). Could these flavors be extended to prepopulate the install instructions in the same manner?

[fmichonneau]

I believe this issue has now been addressed with the recent changes to how the installation instructions are organized in the repository. Feel free to re-open if needed.