Split setup instructions

[rgaiacs]

Work in progress. Don't merge it yet.

This is an prove of concept to address #729.

@karthik What do you think?

[wking]

On Tue, Sep 23, 2014 at 05:05:47PM -0700, Raniere Silva wrote:

• Split setup instructions

-- File Changes --

A README-LONG.md (589)
M README.md (540)

I don't think the README splitting should go in the same commit as the setup splitting. There's also some trailing whitespace here, which I'm sure you just copy/pasted, but it's nice to clean it up while you're touching it ;).

A _includes/setup/firefox-sql.html (27)

There are duplicate “instead”s here, copied from the original source. An additional commit (or follow-up PR) to clean that up would be good.

A _includes/setup/skeleton.html (111)

Love it. For a follow-up commit, flags for the OSes would be nice too ;).

A _includes/setup/windows-editor.html (13)

Some of the text (e.g. “or have other tools like Git launch it for you”) would be nice to adjust depending on what the workshop has enabled. For example, once we get Mercurial setup instructions, enabling Mercurial but disabling Git should replace the example editor launcher. Food for follow-up commits.

And it would be even nicer if all of this setup knowledge lived in a separate #102-style repository from all the lesson code, since there's only a very weak link between them, but that's just me wishing ;).

[gvwilson]

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.)

[wking]

On Tue, Sep 23, 2014 at 05:58:09PM -0700, Greg Wilson wrote:

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.)

See also #310 and #316. The comments there were just about duplicate instructions (in the original #310 post). Links back to “the split layout is confusing” arguments would be nice. I remember some of the discussion, but I can't turn it back up now. Ideally there should be a way to satisfy both @karthik and others who prefer the many-files approach as well as folks who were confused by its intial implementation. If we can collect that feedback in one place it would be easier to try and see a way out.

[wking]

On Tue, Sep 23, 2014 at 06:32:59PM -0700, W. Trevor King wrote:

Links back to “the split layout is confusing” arguments would be nice.

Some of that discussion is in #415, starting with 1.

[wking]

On Tue, Sep 23, 2014 at 06:57:57PM -0700, W. Trevor King wrote:

Some of that discussion is in #415, starting with 1.

1: https://github.com/swcarpentry/bc/pull/415#issuecomment-44602916

The only discuss@ thread I've found so far is @jduckles request for comment 1, but there were no replies.

My current feeling is that the single-file, no-template approach (#316) helped folks avoid looking at templates (which could be intimidating for folks unfamiliar with templates?). But since #415 we've had templates again, and folks haven't complained because they can just tweak their 'lessons' config to enable/disable certain blocks. No need to look at the templates anymore, unless you need even more flexibility. I like this PR, because it makes it easier to separate the template logic in the skeleton file, and keep the install instructions each isolated in their own files. I think it should be even less scary than the current approach, because folks tweaking a particular set of install instructions won't even need to see:

{% if page.lessons contains 'Bash' %} … {% endif %}

They'll just open up _includes/setup/overview-bash.html. That seems more user-friendly to me.

 id:88891640-6BAD-442F-B26A-5ECBAE4B8002@ou.edu

[gvwilson]

@r-gaia-cs is this still relevant given the planned reorganization of the repo?

[rgaiacs]

I'm closing this due the reorganization of the repo.