Duplication of setup instructions and sync issues

[LHurst-UoB]

I'm concerned about the duplication of information between the setup instructions in the workshop template (_includes/swc/setup.html for SWC) and the workshops (e.g. shell-novice/setup.html).

As seen in #632, collectively we're failing to keep the setup instructions in both places in sync resulting in the pair not being cohesive and, sometimes, one or other incorrect despite fixes incorporated in the reverse.

I have no idea what the answer is, if there is a good one (hence this is an issue not a merge request), since there's good reason for having the directions in both places however they also should be identical.

Since the shell and git content are mandatory parts of a SWC workshop, the template could link to the shell-novice setup instructions instead (although it won't be included in the body of the landing page - this is a big con to this, I think)?

Another potential solution is a shared materials git submodule that's included in both repositories containing a single setup.(html/md) include file? This is how we manage shared content in our internal courses but, again, I expect there are issues (and it's an element of additional complexity) with this approach.

[LHurst-UoB]

I've noted that DC links to the lessons' setup pages, instead of duplicating the instructions in the workshop template, in _includes/dc/setup.html.

My inclination is to submit a PR to change _includes/swc/setup.html to do the same, deduplicating the information, unless anyone has strong feelings for not doing so?

[brownsarahm]

Thanks for the issue, this is a known problem and there's an open RFC about changing the instructions for SWC & LC to mirror the recently changed format of the DC workshops. The conversation there seems to gotten a little off track talking about schedules instead of setup instructions. This is a good reminder to revisit that and possibly separate the discussion into two points and aim to resolve the setup instructions portion of it soon (up to delays caused by people taking end of year vacations and that probably also interfering with the lesson infrastructure committee meeting that's usually 4th Wednesday of the month).

[LHurst-UoB]

Hi,

I'm not sure how this is related - the RFC seems to be about improving the modularity of the workshop template (something we've already been working on internally and I've add a long comment about that work to the RFC) but this issue is specifically that swc's setup.html duplicates the lessons setup instructions in contrast to dc's setup.html that links to them.

I don't see this as an issue of modularity of the template itself but a duplication of information in the swc version of that section of materials (dc only mentioned as it demonstrates an alternative approach).

Thinking more about it today, I'm leaning more toward a PR to bring the swc page inline with the dc page (and prevent future disparity between the workshop template and the sessions one).

Laurence

[brownsarahm]

Hi Laurence,

The proposal to make it modular is when the DC lessons switched from instructions in the workshop template repo to links. So, if that RFC is approved, then the workshop template will be swtiched to links for SWC and LC.

[LHurst-UoB]

Hi brownsarahm,

I can’t see any mention of updating the setup instructions in the RFC? If that’s the intention perhaps it should be explicitly mentioned otherwise it will get overlooked or ignored by others (such as me!) who presume that as it’s not mentioned it’s outside the scope of it?

Laurence

[brownsarahm]

You are correct, it's not mentioned explicitly in the new RFC. The details of how the DC changes were implemented is linked to via the previous RFC and the PR. Those mention and show that the setup instructions for DC would be moved to individual repos and because of the reference to them in the new proposal, I expected parallel changes for LC & SWC.

@fmichonneau commented previously that the new RFC is the correct place to discuss issues with the setup information for SWC and LC prior to implementation on the PR about Catalina