Move setup instructions to a separate page

[tracykteal]

For us to use this for a Data Carpentry workshop template, I'd want to have the setup instructions on a separate page, with a link to the Setup instructions at the bottom of the page. I've heard that it's both intimidating and overwhelming to people who are coming to this intro landing page to have all that information.

You can see that generally implemented here
http://www.datacarpentry.org/workshop-template/

I'll put in a PR in this repo that would do this, and we can discuss if we want to make that switch.

[tracykteal]

Before I get too far down this path, this is the idea for moving the setup instructions to a different file than index.html and also creating a modular system, so you can 'includes' the topics you're teaching from just listing them in a YAML header

https://github.com/tracykteal/workshop-template

Index: https://tracykteal.github.io/workshop-template/

Setup page: https://tracykteal.github.io/workshop-template/setup/

In _extras/setup.md an instructor would list in the YAML the topics they're teaching and then it would 'includes' the setup instructions for those tools, pulling that information in from e.g. _includes/setup/python.html and _includes/setup/shell.html

I think this would make it easier to maintain up-to-date instructions and easier for the instructors too. A downside is that instructors would have to update another file than just index.html, but I think if we add the info, they can figure it out, and editing YAML is easier than the blocks of HTML as it is now.

@rgaiacs @k8hertweck @naupaka @wking thoughts?

[naupaka]

Sounds like a good general plan to me. I am not sure of all of the intricacies of the Jekyll-fu y'all are using to make this hang together - but would it be possible to have said setup.md at the root of the repo instead of in the _extras/ folder? Or even call it something like index-setup.md.

I'm just thinking in terms of discoverability - it can be hard to know which subfolder to dig into to modify when setting up a new workshop site. The advantage of just hacking on index.html is that people can come in and figure that out on their own even without too much in the way of instruction.

[tracykteal]

It could be in the main root rather than _extras. It just wouldn't appear in that drop-down 'extras' menu/tab at the top of the page. I'm not sure how important it is to have it appear there though, as I don't really know how people are using the page and if they're looking there.

I agree that it's nice if all the changes are in index.html, but I think the 'edit just the YAML in a different file' might be an OK tradeoff versus people having to edit those HTML chunks. It does in the current directions say "This is the other place where people frequently make mistakes". We can set it so the default set of instructions is for the most commonly taught software - I think shell, Python and github, so fewer people have to edit this at all.

There are other ways to set universal parameters that could affect all pages, by putting things in _data, but I don't think we want to make that significant of a change.

[rgaiacs]

For us to use this for a Data Carpentry workshop template, I'd want to have the setup instructions on a separate page, with a link to the Setup instructions at the bottom of the page.

No problem for me.

I'll put in a PR in this repo that would do this.

Thanks for the pull request.

In _extras/setup.md an instructor would list in the YAML the topics they're teaching and then it would 'includes' the setup instructions for those tools, pulling that information in from e.g. _includes/setup/python.html and _includes/setup/shell.html

I think this would make it easier to maintain up-to-date instructions and easier for the instructors too. A downside is that instructors would have to update another file than just index.html, but I think if we add the info, they can figure it out, and editing YAML is easier than the blocks of HTML as it is now.

I'm against the use of YAML header. We had this conversation in the past and the YAML header (1) makes harder for novices to add their own instructions since they need to learn "advanced" Jekyll and (2) make harder to maintain the file due the nest for/if clauses.

If we are moving to have a separate setup file I will suggest to use

{% comment %} Remove this line if you are not teaching Python {% endcomment %}  {% include setup/python.html %}
{% comment %} Remove this line if you are not teaching R {% endcomment %}  {% include setup/R.html %}
{% comment %} Remove this line if you are not teaching shell {% endcomment %}  {% include setup/shell.html %}

instead of

{% if page.software contains "Python" %}
   {% include setup/python.html %}
{% endif %}

{% if page.software contains "R" %}
  {% include setup/R.html %}
{% endif %}

{% if page.software contains "shell" %}
  {% include setup/shell.html %}
{% endif %}

If the instructor forget to remove some of the lines the only side effect is that some students will install all more tools they will need on the workshop which in my opinion is better than a student that will show up with one or more tools missing.

Sounds like a good general plan to me. I am not sure of all of the intricacies of the Jekyll-fu y'all are using to make this hang together - but would it be possible to have said setup.md at the root of the repo instead of in the _extras/ folder? Or even call it something like index-setup.md.

We probably can solve this with some HTTP redirect hack. For example, have the content in setup.md and

<meta http-equiv="Refresh" content="0; url=/setup/" />

in _extras/setup.md to redirect the user to the content.

[danmichaelo]

Should we try moving forward with this? I just created #535, but it seems to be more or less the same idea as discussed here, so I'm closing that issue in favour of this.

I generally agree with the latest proposal by @rgaiacs.

[fmichonneau]

the installation instructions have been revamped.