Split setup instructions #738
Conversation
Attend to address swcarpentry#729 by splitting the setup instructions to make easy for instructor to find the file that he/she need to edit. Some changes in the README.md to make it smaller and creation of README-LONG.md for the long version of instructions to setup the bootcamp homepage.
|
On Tue, Sep 23, 2014 at 05:05:47PM -0700, Raniere Silva wrote:
I don't think the README splitting should go in the same commit as the
There are duplicate “instead”s here, copied from the original source.
Love it. For a follow-up commit, flags for the OSes would be nice too
Some of the text (e.g. “or have other tools like Git launch it for And it would be even nicer if all of this setup knowledge lived in a |
|
I'm -1 on this: we got rid of precisely this organization months ago because people didn't like it. (See @jdblischak's comment on #729.) |
|
On Tue, Sep 23, 2014 at 05:58:09PM -0700, Greg Wilson wrote:
See also #310 and #316. The comments there were just about duplicate |
|
On Tue, Sep 23, 2014 at 06:57:57PM -0700, W. Trevor King wrote: The only discuss@ thread I've found so far is @jduckles request for My current feeling is that the single-file, no-template approach {% if page.lessons contains 'Bash' %} They'll just open up _includes/setup/overview-bash.html. That seems |
|
@r-gaia-cs is this still relevant given the planned reorganization of the repo? |
|
I'm closing this due the reorganization of the repo. |
…tions Ivan brought this idea back up in maintainers@ recently [1]. I think the last time it was raised seriously was [2], which has reasonable links into earlier discussion. The main argument against tags was that it was too hard to find the source for a particular line you wanted to tweak [3]. This commit restores our old liquid templating to show/hide sections *without* splitting the sections out into sub-files (e.g. bc#738 had _includes/setup/linux-editor.html). If we keep everything in the index file, we can have tags and instructors can either adjust the tags or easily find/edit/delete as they see fit. A few notes on the implementation: * I've gone with double quotes in the YAML front matter for consistency with the other entries, but stuck with the original (from swcarpentry/bc) single quotes for the liquid conditionals. * I've kept "check" and "VM" out of the default tools list to match the current display, but we may want to enable everything and write a stronger message about removing stuff you don't need to avoid repeating the problems we had with check being visible by default [4]. Because folks will have to tweak the tools list if they want to enable the "check" or "VM" sections, I've added comments at the beginning of each section pointing instructors back up at the YAML front matter. * I've moved the "check" section out of the Python section, because while the tool doesn't currently test R packages, it does test Git, Bash, text editors, etc., and it could certainly be extended to test R if someone with R knowledge wanted to chip in (although it's harder to *run* the script on Windows without bundling Python) [5]. [1]: http://lists.software-carpentry.org/pipermail/maintainers_lists.software-carpentry.org/2016-March/000179.html Subject: Re: [Maintainers] Vote needed for setup instructions Date: Thu, 10 Mar 2016 12:05:33 -0500 Message-ID: <CAJpTZ0DPYKgu2fbi6dZ3XvZVyed0MwmS-jTR-e-Y3uYoZKoctQ@mail.gmail.com> [2]: swcarpentry/DEPRECATED-bc#738 [3]: swcarpentry/DEPRECATED-bc#729 (comment) [4]: carpentries#278 [5]: carpentries#136 (comment)
…tions Ivan brought this idea back up in maintainers@ recently [1]. I think the last time it was raised seriously was [2], which has reasonable links into earlier discussion. The main argument against tags was that it was too hard to find the source for a particular line you wanted to tweak [3]. This commit restores our old liquid templating to show/hide sections *without* splitting the sections out into sub-files (e.g. bc#738 had _includes/setup/linux-editor.html). If we keep everything in the index file, we can have tags and instructors can either adjust the tags or easily find/edit/delete as they see fit. A few notes on the implementation: * I've gone with double quotes in the YAML front matter for consistency with the other entries, but stuck with the original (from swcarpentry/bc) single quotes for the liquid conditionals. * I've kept "test" and "VM" out of the default tools list to match the current display, but we may want to enable everything and write a stronger message about removing stuff you don't need to avoid repeating the problems we had with the installation-test link being visible by default [4]. Because folks will have to tweak the tools list if they want to enable the "test" or "VM" sections, I've added comments at the beginning of each section pointing instructors back up at the YAML front matter. * I've moved the "test" section out of the Python section, because while the tool doesn't currently test R packages, it does test Git, Bash, text editors, etc., and it could certainly be extended to test R if someone with R knowledge wanted to chip in (although it's harder to *run* the script on Windows without bundling Python) [5]. The new header separates the test section from the previous section. [1]: http://lists.software-carpentry.org/pipermail/maintainers_lists.software-carpentry.org/2016-March/000179.html Subject: Re: [Maintainers] Vote needed for setup instructions Date: Thu, 10 Mar 2016 12:05:33 -0500 Message-ID: <CAJpTZ0DPYKgu2fbi6dZ3XvZVyed0MwmS-jTR-e-Y3uYoZKoctQ@mail.gmail.com> [2]: swcarpentry/DEPRECATED-bc#738 [3]: swcarpentry/DEPRECATED-bc#729 (comment) [4]: carpentries#278 [5]: carpentries#136 (comment)
Work in progress. Don't merge it yet.
This is an prove of concept to address #729.
@karthik What do you think?