search

carpentries / workshop-template

The Carpentries Workshop Template
https://carpentries.github.io/workshop-template/
Other
234 stars 521 forks source link

Organizing installation instructions by software versus platform #59

Closed jcamins closed 10 years ago

jcamins commented 10 years ago

I notice the current template organizes installation instructions by software (separate sections for Bash, git, Python, R, SQLite) rather than by platform as used to be the case. What was the reason for the change?

My knee-jerk reaction is that organizing by platform was much more useful to students, because at least some of them are not going to know what "git" is until after the workshop, and most people know whether they have Windows, Linux, or Mac OS X.

jcamins commented 10 years ago

Since we use Jekyll, it should be easy to add a flag in the metadata header to toggle the git/Python/R/SQLite installation instructions so that the teachers don't have to remove three R sections, if that was the reason for the change.

rgaiacs commented 10 years ago

I notice the current template organizes installation instructions by software (separate sections for Bash, git, Python, R, SQLite) rather than by platform as used to be the case. What was the reason for the change?

Organizing by software make easy for instructors edit by hand the home page.

Since we use Jekyll, it should be easy to add a flag in the metadata header to toggle the git/Python/R/SQLite installation instructions so that the teachers don't have to remove three R sections, if that was the reason for the change.

You aren't the first one to propose this. We tried it before but when instructors want to edit the installation instructions they had troubles to do it because of Jekyll/Liquid markup.

gvwilson commented 10 years ago

Opinion seems split pretty equally on platform-then-package vs. package-then-platform, so I grouped by package so that website creators would only have to delete one (large) section (because they're not teaching a particular package) rather than several scattered sections (because they always have to cover all three platforms).

gvwilson commented 10 years ago

@jduckles added that; people found it less easy to understand and use than simply deleting the sections of the template. (I think many of our instructors are new to templating.)

jcamins commented 10 years ago

I see. Thanks for the clarification. If there were more of a consensus that grouping by platform was preferable, we could probably use a Jekyll plugin to keep the input grouped by package but group the output by platform. As there isn't a consensus, of course, keeping it the way it is makes as much sense as not.