An "Installation Lesson" and the right configuration for a workshop are two
different concerns. A workshop could be comprised of Bash, Git & Python, or
Bash, Mercurial and Matlab, or or or... So I really do like the approach we use
now to leave configuration directives in the hands of the instructor of a
specific workshop.
That being said, each lesson itself could have an `install.md` that the lessons
references with instructions on how to get dependencies necessary for the
lesson on a Mac, Windows or Linux. This solves the web-only learner issue that
started the thread. It also scales gracefully.
As the number of contributed lessons grow, I worry that an uber installation
guide for all-the-things is not on a track to solve a novice learner's
problems. It becomes yet another place to change configuration directives and
unless it is actively maintained by all the maintainers, it will fall out of
step with the preferred config.
Greg, can you bring this to the Lesson Developers/Maintainers with a request to
come up with a way forward for install instructions for web-based learners?
Regards,
---
Jonah Duckles
Software Carpentry, Executive Director
http://software-carpentry.org
From: Christina Koch <[email protected]>
Reply: Christina Koch <[email protected]>
Date: February 22, 2016 at 8:20:28 AM
To: Andrew Walker [EAR] <[email protected]>
CC: [email protected] <[email protected]>
Subject: Re: [Discuss] installation instructions
To add something completely different to the mix - Sarah Stevens and I are in
the process of making "how to" installation videos for both windows/mac. They
could go on the main SWC lessons page, on individual lesson pages, or in a new
"installation" lesson.
Christina
On Sat, Feb 20, 2016 at 11:58 AM, Andrew Walker [EAR] <[email protected]>
wrote:
Hi all,
I suspect the best way to do this would be to create 'special workshop'
from the template that includes all installation instructions and some
generic background information rather than information about a particular
workshop. Call it something like 'installation' in the swcarpentry
organisation and we would get a useful site
(swcarpentry.github.io/installation) and hopefully have something we can
keep in sync with the instructions we present to workshop participants.
There are a few important points that I think we should keep in mind:
* We should keep a set of installation instructions in the workshop
webpages (and thus in the template). Workshop organisers / lead
instructors need to taylor these both for content (avoid telling
participants at a R-based workshop to install python) and "level" (if you
know you have absolute beginners the python test scripts seem to be more
trouble than they are worth, but they seem to work well with more advanced
groups).
* Any central instructions need be kept in sync with the per-workshop
instructions. Fixes like the problem with nano last summer need to
propagate everywhere and we should avoid telling participants to do two
different things depending on where they look.
* It should be possible to arrange this with a bit of careful thought and
git-foo. It would need reasonable communication between the
workshop-template maintainer and whoever looks after the installation
instructions repository and a clear idea about the direction that patches
to installation instructions should travel (they could go from the
installation instructions repository to the workshop-template or the other
way; I suspect mixing directions would result in a mess).
Ultimately this discussion probably belongs in an issue in a repository
somewhere.
Best wishes,
Andrew
‹
Dr Andrew Walker
NERC Independent Research Fellow
School of Earth and Environment
University of Leeds
On 19/02/2016, 18:14, "Discuss on behalf of Cam Macdonell"
<[email protected] on behalf of
[email protected]> wrote:
>May I suggest that an admin on the SWC github site create a repo named
>"install-docs" (or something better) that we can begin to work on?
>
>Cam
>
>Quoting Karin Lagesen <[email protected]>:
>> I have for some time wanted a "Resources" section on our website, with
>>stuff
>> that our community can use. IMO, this section would include a SWC pitch,
>> logos, other advertising material, install instructions, debug install
>> stuff, and other mostly static things that we, the community, would need
>> rapid access to.
>>
>> Karin
>>
>>
>> On 18.02.2016 02:26, Bennet Fauber wrote:
>> >I think that separting the installation instructions is good idea.
>> >That might make them easier for people trying to use the published
>> >material but who are not attending a specific workshop.
>> >
>> >In the spirit of writing functions and calling them from larger
>> >scripts, wouldn't we want to write a function for each installation:
>> >bash, git, python, et al., and then refer to the ones pertinent to the
>> >workshop from the workshop site? Then the same installation
>> >instructions could be used for an Intro Python and an Intermediate
>> >Python.
>> >
>> >
>> >
>> >On Wed, Feb 17, 2016 at 7:15 PM, Moreau, John (UMKC-Student)
>> ><[email protected]> wrote:
>> >>Matt et al:
>> >>
>> >>Perhaps this is the crux of the problem. We no longer have
>>installation
>> >>instructions outside of the workshop pages. More experienced
>>instructors may
>> >>know to check the workshop template on GitHub. However, for newer
>> >>instructors, potential workshop hosts, and drive-by site visitors,
>>there¹s
>> >>no clear directions.
>> >>
>> >>Thinking about the problem from the perspective of a novice learner,
>>their
>> >>first instinct will be to check the website. After coming up short,
>>some
>> >>people will become frustrated and abandon the search. Here¹s where an
>>expert
>> >>might say ³Why didn¹t you just* google for {program needed}?² Because
>>the
>> >>novice learner lacks the mental models of an expert, they may not
>>know what
>> >>search terms to use. The Shell lessons suffer from this problem more
>>than
>> >>most:
>> >>
>> >>· Nowhere on the lesson landing page
>> >>(http://swcarpentry.github.io/shell-novice/) do we mention the term
>>³Bash²
>> >>
>> >>· The ³Introducing the Shell² page
>> >>(http://swcarpentry.github.io/shell-novice/00-intro.html) does not
>>use the
>> >>term ³Bash² until the seventh paragraph
>> >>
>> >>· The intro page does not directly tell a novice learner that
>>the
>> >>standard Git for Windows installation includes Bash.
>> >>
>> >>· The intro page does mention that the Bash shell is the
>>default
>> >>shell on many modern UNIX implementations. A novice learner may not
>>know
>> >>that Mac OS now uses a UNIX engine and uses Bash for its command line
>> >>terminal. They also may not know how to access the terminal.
>> >>
>> >>· If a Linux user doesn¹t know about the Unix command line, I
>>really
>> >>want to ask them how they got Linux on their machine in the first
>>place.
>> >>
>> >>
>> >>
>> >>For these reasons, I suggest that we should add installation
>>instructions to
>> >>either the lesson pages or as a separate ³lesson². Before Greg (or
>>anyone
>> >>else) says it, yes, I know ³Pull requests are always welcome². Let me
>>ask
>> >>the community - Would you rather have:
>> >>
>> >>A separate install ³lesson² and links from the other lessons to that
>>install
>> >>page
>> >>
>> >>-OR-
>> >>Installation information within each separate lesson?
>> >>
>> >>
>> >>
>> >>John Moreau
>> >>
>> >>* http://swcarpentry.github.io/instructor-training/05-expertise.html
>> >>
>> >>
>> >>
>> >>From: Discuss [mailto:[email protected]] On
>> >>Behalf Of Matt Davis
>> >>Sent: Wednesday, February 17, 2016 5:05 PM
>> >>To: Markus Mueller <[email protected]>;
>> >>[email protected]
>> >>Subject: Re: [Discuss] installation instructions
>> >>
>> >>
>> >>
>> >>Hi Markus,
>> >>
>> >>
>> >>
>> >>Our workshop webpages have software installation instructions. We
>>used to
>> >>have those on software-carpentry.org, but I couldn't find them so
>>here's the
>> >>website of an upcoming workshop:
>> >>https://joshwaterfall.github.io/2016-02-16-NIH/
>> >>
>> >>
>> >>
>> >>Best,
>> >>
>> >>Matt
>> >>
>> >>
>> >>
>> >>On Wed, Feb 17, 2016 at 2:53 PM Markus Mueller
>> >><[email protected]> wrote:
>> >>
>> >>Dear listers,
>> >>
>> >>
>> >>
>> >>I am a new instructor (or soon to be one) and started having a closer
>>look
>> >>at the software carpentry lesson material. I first had a look at the
>> >>instructor guide
>> >>(http://swcarpentry.github.io/shell-novice/instructors.html) and only
>>found
>> >>some general tips and hints about which tools to use and how to
>>install them
>> >>(my interested would here apparently be how to get a unix shell to
>>run on
>> >>windows).
>> >>
>> >>
>> >>
>> >>I apologize if I missed something, but otherwise would be glad if
>>somebody
>> >>could point me to the installation guidelines (that the page above
>>somehow
>> >>hints at).
>> >>
>> >>
>> >>
>> >>
>> >>
>> >>Cheers,
>> >>
>> >>
>> >>
>> >>Markus
>> >>
>> >>
>> >>
>> >>________________________________
>> >>
>> >>
>> >>Please consider the environment before printing this email
>> >>Warning: This electronic message together with any attachments is
>> >>confidential. If you receive it in error: (i) you must not read, use,
>> >>disclose, copy or retain it; (ii) please contact the sender
>>immediately by
>> >>reply email and then delete the emails.
>> >>The views expressed in this email may not be those of Landcare
>>Research New
>> >>Zealand Limited. http://www.landcareresearch.co.nz
>> >>
>> >>_______________________________________________
>> >>Discuss mailing list
>> >>[email protected]
>>
>>>>http://lists.software-carpentry.org/mailman/listinfo/discuss_lists.soft
>>>>ware-carpentry.org
>> >>
>> >>
>> >>_______________________________________________
>> >>Discuss mailing list
>> >>[email protected]
>>
>>>>http://lists.software-carpentry.org/mailman/listinfo/discuss_lists.soft
>>>>ware-carpentry.org
>> >
>> >_______________________________________________
>> >Discuss mailing list
>> >[email protected]
>>
>>>http://lists.software-carpentry.org/mailman/listinfo/discuss_lists.softw
>>>are-carpentry.org
>> >
>>
>>
>> _______________________________________________
>> Discuss mailing list
>> [email protected]
>>
>>http://lists.software-carpentry.org/mailman/listinfo/discuss_lists.softwa
>>re-carpentry.org
>
>_______________________________________________
>Discuss mailing list
>[email protected]
>http://lists.software-carpentry.org/mailman/listinfo/discuss_lists.softwar
>e-carpentry.org
_______________________________________________
Discuss mailing list
[email protected]
http://lists.software-carpentry.org/mailman/listinfo/discuss_lists.software-carpentry.org
--
Christina Koch - Research Computing Facilitator,
University of Wisconsin - Madison, Center for High Throughput Computing
Advanced Computing Initiative; Wisconsin Institute for Discovery; ACI-REF
[email protected] // (608) 316 - 4041 // tinyurl.com/ChristinaCalendarCHTC
_______________________________________________
Discuss mailing list
[email protected]
http://lists.software-carpentry.org/mailman/listinfo/discuss_lists.software-carpentry.org_______________________________________________
Discuss mailing list
[email protected]
http://lists.software-carpentry.org/mailman/listinfo/discuss_lists.software-carpentry.org
