Proposal to import installation instructions from other lessons

[rgaiacs]

This is a working in progress. Feedback from @tracykteal, @jduckles, @ChristinaLK, @wking et al. are welcome.

Summary

Installation instructions will be assembled on the fly by learners web browsers using client side Javascript to pull and inject the information from the lessons that the leader instructor configured. The Javascript code is almost identical to the one that we are using in the all-in-one episodes page and in the figures page.

Long Description

I'm writing a blog post to start the discussion.

[katrinleinweber]

Blog post is live at https://software-carpentry.org/blog/2018/01/proposal-workshop-template.html

[ChristinaLK]

Don't have time to read in detail right now, but I like having install instructions on both lesson pages + workshop template page.

[rgaiacs]

but I like having install instructions on both lesson pages + workshop template page.

The instructions will be in both places for readers. My proposal is in the line of let's avoid duplication and keep the source information in just one place in the spirit of eating our own dog food. In addition to it, let's save leader instructor time when creating the workshop page.

[ChristinaLK]

Sorry @rgaiacs what I meant was I like having the instructions available to read in both places but only maintained in one. So I am 100% on board with this proposal. :))))

[tracykteal]

I'm also +1 on the idea of having one set of installation instructions that get pulled into different places. As you note things are in different places right now, and instructors interact with the lessons differently, so there will be some documentation and technical issues to work out, but I agree this is worth pursuing.

[jduckles]

I like this overall approach, one important caveat is that XSS browser security rules may prevent people from loading non-GitHub hosted (ie not *.github.io) fragments for their installation instructions. So if someone hosts a lesson off GitHub and wants those install instructions to be includable (ie all DC lessons are hosted at datacarpentry.org), I'm not sure by default things will work. I could be wrong, but I seem to recall a particular XSS header being required to be changed on the hosting server to allow these kinds of remote includes (this can't be assumed to be possible to change by all lesson developers/hosting sites). Before we implement this I'd like us to test to make sure it will work in various lesson hosting configurations.

[rgaiacs]

I like this overall approach, one important caveat is that XSS browser security rules may prevent people from loading non-GitHub hosted (ie not *.github.io) fragments for their installation instructions. So if someone hosts a lesson off GitHub and wants those install instructions to be includable (ie all DC lessons are hosted at datacarpentry.org), I'm not sure by default things will work.

@jduckles I pushed a copy of this pull request to GitLab, https://gitlab.com/rgaiacs/carpentries-workshop-template, that is instructed to load the content from GitHub (see https://gitlab.com/rgaiacs/carpentries-workshop-template/blob/proposal-remote-instructions/index.md), and I didn't get any warning when loading https://rgaiacs.gitlab.io/carpentries-workshop-template/ in Chrome and Firefox.

I'm not sure by default things will work.

Looks like they will.

Before we implement this I'd like us to test to make sure it will work in various lesson hosting configurations.

If you can provide a list of all the configurations that you want to support, I'm happy to provide some implementations.

[jduckles]

@rgaiacs Thanks for checking, this was a lifetime ago when I ran into these problems. I think it may be connected to <script></script> includes only as running someone else's JavaScript is where things can get dicey. You could inadvisably end-around the browser security with Access-Control-Allow-Origin headers on the server side. As long as we've tested this across domains I'm comfortable moving forward.

[rgaiacs]

@twitwi asked about the case of learners and instructors that have JavaScript disabled in their web browers. I believe that less than 1% of our demographic would disable JavaScript but we could have a some text with the link for the instructions. For example, abccf3d implements it.

[c-martinez]

This looks like a great idea! Any plans as to when it would be merged? Is there anything preventing it being merged? Anything I could help out with?

[rgaiacs]

Any plans as to when it would be merged?

I don't think that this proposal was accepted. @fmichonneau are we voting on this soon?

Is there anything preventing it being merged?

This requires a change in the lesson style and coordination for this to be in place before this one is merged.

Anything I could help out with?

@fmichonneau was working on other ideas for workshop pages that I'm not sure if he is confident to share with.

[danmichaelo]

Interesting alternative to #408. Logically, it makes a lot of sense to keep the instructions together with the lesson and only there. Engineering wise, I'm a little bit more skeptical. The risk that this breaks might actually be small in practice given the structural stability of the lessons, but in principle the approach of including content from another webpage directly like this seems a bit brittle/risky/unorthodox :)

Btw. do you have a demo still working? On https://rgaiacs.gitlab.io/carpentries-workshop-template/ I get

Uncaught TypeError: Failed to execute 'appendChild' on 'Node': parameter 1 is not of type 'Node'.
    at XMLHttpRequest.xmlHttp.(/carpentries-workshop-template/anonymous function).onreadystatechange (https://rgaiacs.gitlab.io/carpentries-workshop-template/:219:17)

(which reminds me of: there should be error handling and fallback in any case :))

[rgaiacs]

@danmichaelo I believe that I had to update the gh-pages branch of the lessons that I was using to handle another pull request. This is the reason that you got the error.

[sstevens2]

I'm here because I was helping someone with a workshop webpage today and thinking again about how weird it is that the setup is the only part at the bottom that is not broken out into the _includes directories. So I found #408 and then it lead here.

Is this still in the works? Because I love the idea of maintaining directions in one place and making it easier for folks to put the workshop website together.

[fmichonneau]

superseeded by carpentries/maintainer-RFCs#3