Commit c5058dfc authored by Rémi Emonet's avatar Rémi Emonet
Browse files

[DOI: 10.5281/zenodo.838778] Rebuilt HTML files for release 2017.08 

jekyll version: jekyll 3.4.3
parent 1e925f93

01-design/index.html

0 → 100644
+393 −0
Original line number Diff line number Diff line 
<!doctype html>

<html lang="en">

  <head>

    <meta charset="utf-8">

    <meta http-equiv="X-UA-Compatible" content="IE=edge">

    <meta http-equiv="last-modified" content="2017-08-04 00:26:58 +0200">

    <meta name="viewport" content="width=device-width, initial-scale=1">

    <!-- meta "search-domain" used for google site search function google_search() -->

    <meta name="search-domain" value="/swc-releases/2017.08/lesson-example">

    <link rel="stylesheet" type="text/css" href="../assets/css/bootstrap.css" />

    <link rel="stylesheet" type="text/css" href="../assets/css/bootstrap-theme.css" />

    <link rel="stylesheet" type="text/css" href="../assets/css/lesson.css" />

    

    <link rel="shortcut icon" type="image/x-icon" href="/favicon-swc.ico" />

    

    <!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries -->

    <!-- WARNING: Respond.js doesn't work if you view the page via file:// -->

    <!--[if lt IE 9]>

	<script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>

	<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>

	<![endif]-->

    <title>Lesson Title: Lesson Design</title>

  </head>

  <body>

    <div class="container">

      

<nav class="navbar navbar-default">

  <div class="container-fluid">

    <div class="navbar-header">

      <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1" aria-expanded="false">

        <span class="sr-only">Toggle navigation</span>

        <span class="icon-bar"></span>

        <span class="icon-bar"></span>

        <span class="icon-bar"></span>

      </button>



      

      



      

      <a class="navbar-brand" href="../">Home</a>



    </div>

    <div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">

      <ul class="nav navbar-nav">



	

        <li><a href="../conduct/">Code of Conduct</a></li>



	

        

        <li><a href="../setup/">Setup</a></li>

        <li class="dropdown">

          <a href="../" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Episodes <span class="caret"></span></a>

          <ul class="dropdown-menu">

            

            <li><a href="../01-design/">Lesson Design</a></li>

            

            <li><a href="../02-tooling/">GitHub, Markdown, and Jekyll</a></li>

            

            <li><a href="../03-organization/">Lesson Organization</a></li>

            

            <li><a href="../04-formatting/">Formatting</a></li>

            

            <li><a href="../05-checking/">Checking and Previewing</a></li>

            

            <li><a href="../06-rmarkdown-example/">Using RMarkdown</a></li>

            

            <li><a href="../07-maintenance/">Maintenance</a></li>

            

            <li><a href="../08-coffee/">Coffee Break</a></li>

            

	    <li role="separator" class="divider"></li>

            <li><a href="../aio/">All in one page (Beta)</a></li>

          </ul>

        </li>

	



	

	

        <li class="dropdown">

          <a href="../" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Extras <span class="caret"></span></a>

          <ul class="dropdown-menu">

            <li><a href="../reference/">Reference</a></li>

            

            <li><a href="../about/">About</a></li>

            

            <li><a href="../discuss/">Discussion</a></li>

            

            <li><a href="../figures/">Figures</a></li>

            

            <li><a href="../guide/">Instructor Notes</a></li>

            

          </ul>

        </li>

	



	

        <li><a href="../license/">License</a></li>

	

	<li><a href="/edit/gh-pages/_episodes/01-design.md">Improve this page <span class="glyphicon glyphicon-pencil" aria-hidden="true"></span></a></li>

	

      </ul>

      <form class="navbar-form navbar-right" role="search" id="search" onsubmit="google_search(); return false;">

        <div class="form-group">

          <input type="text" id="google-search" placeholder="Search..." aria-label="Google site search">

        </div>

      </form>

    </div>

  </div>

</nav>





<div class="row">

  <div class="col-md-1">

    <h3>

      

      <a href="../"><span class="glyphicon glyphicon-menu-up" aria-hidden="true"></span><span class="sr-only">lesson home</span></a>

      

    </h3>

  </div>

  <div class="col-md-10">

    

    <h3 class="maintitle"><a href="../">Lesson Title</a></h3>

    

  </div>

  <div class="col-md-1">

    <h3>

      

      <a href="../02-tooling/"><span class="glyphicon glyphicon-menu-right" aria-hidden="true"></span><span class="sr-only">next episode</span></a>

      

    </h3>

  </div>

</div>



<article>

<div class="row">

  <div class="col-md-1">

  </div>

  <div class="col-md-10">

    <h1 class="maintitle">Lesson Design</h1>

  </div>

  <div class="col-md-1">

  </div>

</div>





<blockquote class="objectives">

  <h2>Overview</h2>



  <div class="row">

    <div class="col-md-3">

      <strong>Teaching:</strong> 10 min

      <br/>

      <strong>Exercises:</strong> 0 min

    </div>

    <div class="col-md-9">

      <strong>Questions</strong>

      <ul>

	

	<li><p>How do we design lessons?</p>

</li>

	

      </ul>

    </div>

  </div>



  <div class="row">

    <div class="col-md-3">

    </div>

    <div class="col-md-9">

      <strong>Objectives</strong>

      <ul>

	

	<li><p>Describe the reverse instructional design process.</p>

</li>

	

	<li><p>Describe the purpose and implementation of formative assessments.</p>

</li>

	

      </ul>

    </div>

  </div>



</blockquote>



<p>This episode describes how we go about designing lessons and why.

For more information on how we design lessons and why,

see <a href="http://swcarpentry.github.io/instructor-training/">the instructor training course</a>.</p>



<h2 id="reverse-instructional-design">Reverse Instructional Design</h2>



<p>In principle,

we design lessons in four stages:</p>



<ol>

  <li>

    <p><strong>Conceptual</strong>:

describe who the lesson is for,

what its overall goals are,

and how long it is going to be.

For example,

the lesson might be for people who have taught themselves

how to write page-long statistical analyses in R using RStudio,

but have never written functions or run programs from the Unix shell prompt.

Its overall goal might be to teach them how to write modular multi-page programs

and how to use dplyr to regularize their analyses,

and the time allotted might be half a day.

It’s often helpful to use <a href="http://swcarpentry.github.io/instructor-training/08-memory/">concept maps</a> in this stage.</p>

  </li>

  <li>

    <p><strong>Summative Assessment</strong>:

figure out what learners will do to demonstrate that they have mastered the material.

This is the most important step of the four,

since it is what <em>actually</em> determines the scope of the lesson.

In this case,

the summative assessment might be to write a four-function program

to load, clean up, analyze, and plot a collection of medical data sets.</p>

  </li>

  <li>

    <p><strong>Formative Assessments</strong>:

describe the exercises that learners will do during the lesson.

To switch examples for a moment,

it wouldn’t be fair to ask someone to parallel park on a driving test

if they’d never done it before,

so two formative assessments in a driving course might be

“back up” and “parallel park between some safety cones”.</p>

  </li>

  <li>

    <p><strong>Connect the Dots</strong>:

put the formative assessments in order

and develop lesson episodes to go from one to the next.

It is common to sketch a concept map for each lesson episode,

both to outline its key ideas

and to check that it’s not too big.

The ordering of lesson episodes is constrained by dependencies

but is usually not completely determined by them:

there are often several different orders in which ideas can sensibly be introduced.

It is common to discover a need for more formative assessments at this stage;

to continue with the driving example,

the lesson author might realize that a third exercise on turning while backing up is needed

(since many people initially turn the steering wheel the wrong way when they’re in reverse).</p>

  </li>

</ol>



<p>In practice, the process often looks more like this:</p>



<ol>

  <li>

    <p>Draft the assumptions and major outcomes.</p>

  </li>

  <li>

    <p>Describe the summative assessments for each half day of material

(i.e., one summative assessment for a three-hour lesson and two for a full-day lesson).</p>

  </li>

  <li>

    <p>Write a one- or two-line description of the formative assessments

building up to those summative assessments.

These should be paced at roughly 15-minute intervals,

i.e.,

four per hour.</p>

  </li>

  <li>

    <p>Get early feedback from peers,

particularly on how realistic the time estimates are.</p>

  </li>

  <li>

    <p>Do a second pass to flesh out the assumptions and assessments.</p>

  </li>

  <li>

    <p>Get more feedback.</p>

  </li>

  <li>

    <p>Start writing the lesson content.</p>

  </li>

</ol>



<p>Steps 1-6 are best done in a single Markdown file for easy review;

if you are using this template,

you should call it <code class="highlighter-rouge">_extras/design.md</code>.

Once work starts on step 7,

the detailed milestones should be moved into lesson episode files.

For an example of this,

see the <a href="https://swcarpentry.github.io/python-novice-gapminder/">novice Python lesson using the gapminder data</a>.</p>



<h2 id="what-makes-a-good-formative-assessment">What Makes a Good Formative Assessment</h2>



<p>The two purposes of formative assessment are

(a) to help learners prepare for the summative assessment and

(b) to tell them and their instructor <em>during the lesson</em>

whether they’re making progress (and if not, what obstacles they have hit).

If lesson episodes are 10-15 minutes long,

then formative assessments should take no more than 5 minutes.

This means that formative assessments should be:</p>



<ul>

  <li>multiple choice questions,</li>

  <li>Parsons Problems

(in which the learner is given the parts of the solution in scrambled order

and has to put them in the right order),</li>

  <li>debugging exercises

(in which the learner is given a few lines of code that do the wrong thing

and asked to find and fix the bug), or</li>

  <li>extensions of examples show in the lecture.</li>

</ul>



<p>Good formative assessments do <em>not</em> require learners to write lots of code from scratch:

it takes too long,

there are usually too many possible right solutions to discuss in just a couple of minutes,

and many novices find a blank page (or screen) intimidating.</p>







<blockquote class="keypoints">

  <h2>Key Points</h2>

  <ul>

    

    <li><p>Lessons are design in four stages: conceptual, summative, formative, and connective.</p>

</li>

    

  </ul>

</blockquote>



</article>



<div class="row">

  <div class="col-md-1">

    <h3>

      

      <a href="../"><span class="glyphicon glyphicon-menu-up" aria-hidden="true"></span><span class="sr-only">lesson home</span></a>

      

    </h3>

  </div>

  <div class="col-md-10">

    

  </div>

  <div class="col-md-1">

    <h3>

      

      <a href="../02-tooling/"><span class="glyphicon glyphicon-menu-right" aria-hidden="true"></span><span class="sr-only">next episode</span></a>

      

    </h3>

  </div>

</div>





      

      

<footer>

  <div class="row">

    <div class="col-md-6" align="left">

      <h4>

	Copyright &copy; 2016–2017

	

	<a href="https://software-carpentry.org">Software Carpentry Foundation</a>

	

      </h4>

    </div>

    <div class="col-md-6" align="right">

      <h4>

	

	<a href="/edit/gh-pages/_episodes/01-design.md">Edit on GitHub</a>

	

	/

	<a href="/blob/gh-pages/CONTRIBUTING.md">Contributing</a>

	/

	<a href="/">Source</a>

	/

	<a href="/blob/gh-pages/CITATION">Cite</a>

	/

	<a href="mailto:lessons@software-carpentry.org">Contact</a>

      </h4>

    </div>

  </div>

</footer>



      

    </div>

    

<script src="../assets/js/jquery.min.js"></script>

<script src="../assets/js/bootstrap.min.js"></script>

<script src="../assets/js/lesson.js"></script>

<script>

  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){

  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),

  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)

  })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-37305346-2', 'auto');

  ga('send', 'pageview');

</script>



  </body>

</html>

02-tooling/index.html

0 → 100644
+433 −0

File added.

Preview size limit exceeded, changes collapsed.

03-organization/index.html

0 → 100644
+441 −0

File added.

Preview size limit exceeded, changes collapsed.

04-formatting/index.html

0 → 100644
+607 −0

File added.

Preview size limit exceeded, changes collapsed.

05-checking/index.html

0 → 100644
+324 −0
Original line number Diff line number Diff line 
<!doctype html>

<html lang="en">

  <head>

    <meta charset="utf-8">

    <meta http-equiv="X-UA-Compatible" content="IE=edge">

    <meta http-equiv="last-modified" content="2017-08-04 00:26:58 +0200">

    <meta name="viewport" content="width=device-width, initial-scale=1">

    <!-- meta "search-domain" used for google site search function google_search() -->

    <meta name="search-domain" value="/swc-releases/2017.08/lesson-example">

    <link rel="stylesheet" type="text/css" href="../assets/css/bootstrap.css" />

    <link rel="stylesheet" type="text/css" href="../assets/css/bootstrap-theme.css" />

    <link rel="stylesheet" type="text/css" href="../assets/css/lesson.css" />

    

    <link rel="shortcut icon" type="image/x-icon" href="/favicon-swc.ico" />

    

    <!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries -->

    <!-- WARNING: Respond.js doesn't work if you view the page via file:// -->

    <!--[if lt IE 9]>

	<script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>

	<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>

	<![endif]-->

    <title>Lesson Title: Checking and Previewing</title>

  </head>

  <body>

    <div class="container">

      

<nav class="navbar navbar-default">

  <div class="container-fluid">

    <div class="navbar-header">

      <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1" aria-expanded="false">

        <span class="sr-only">Toggle navigation</span>

        <span class="icon-bar"></span>

        <span class="icon-bar"></span>

        <span class="icon-bar"></span>

      </button>



      

      



      

      <a class="navbar-brand" href="../">Home</a>



    </div>

    <div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">

      <ul class="nav navbar-nav">



	

        <li><a href="../conduct/">Code of Conduct</a></li>



	

        

        <li><a href="../setup/">Setup</a></li>

        <li class="dropdown">

          <a href="../" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Episodes <span class="caret"></span></a>

          <ul class="dropdown-menu">

            

            <li><a href="../01-design/">Lesson Design</a></li>

            

            <li><a href="../02-tooling/">GitHub, Markdown, and Jekyll</a></li>

            

            <li><a href="../03-organization/">Lesson Organization</a></li>

            

            <li><a href="../04-formatting/">Formatting</a></li>

            

            <li><a href="../05-checking/">Checking and Previewing</a></li>

            

            <li><a href="../06-rmarkdown-example/">Using RMarkdown</a></li>

            

            <li><a href="../07-maintenance/">Maintenance</a></li>

            

            <li><a href="../08-coffee/">Coffee Break</a></li>

            

	    <li role="separator" class="divider"></li>

            <li><a href="../aio/">All in one page (Beta)</a></li>

          </ul>

        </li>

	



	

	

        <li class="dropdown">

          <a href="../" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Extras <span class="caret"></span></a>

          <ul class="dropdown-menu">

            <li><a href="../reference/">Reference</a></li>

            

            <li><a href="../about/">About</a></li>

            

            <li><a href="../discuss/">Discussion</a></li>

            

            <li><a href="../figures/">Figures</a></li>

            

            <li><a href="../guide/">Instructor Notes</a></li>

            

          </ul>

        </li>

	



	

        <li><a href="../license/">License</a></li>

	

	<li><a href="/edit/gh-pages/_episodes/05-checking.md">Improve this page <span class="glyphicon glyphicon-pencil" aria-hidden="true"></span></a></li>

	

      </ul>

      <form class="navbar-form navbar-right" role="search" id="search" onsubmit="google_search(); return false;">

        <div class="form-group">

          <input type="text" id="google-search" placeholder="Search..." aria-label="Google site search">

        </div>

      </form>

    </div>

  </div>

</nav>





<div class="row">

  <div class="col-md-1">

    <h3>

      

      <a href="../04-formatting/"><span class="glyphicon glyphicon-menu-left" aria-hidden="true"></span><span class="sr-only">previous episode</span></a>

      

    </h3>

  </div>

  <div class="col-md-10">

    

    <h3 class="maintitle"><a href="../">Lesson Title</a></h3>

    

  </div>

  <div class="col-md-1">

    <h3>

      

      <a href="../06-rmarkdown-example/"><span class="glyphicon glyphicon-menu-right" aria-hidden="true"></span><span class="sr-only">next episode</span></a>

      

    </h3>

  </div>

</div>



<article>

<div class="row">

  <div class="col-md-1">

  </div>

  <div class="col-md-10">

    <h1 class="maintitle">Checking and Previewing</h1>

  </div>

  <div class="col-md-1">

  </div>

</div>





<blockquote class="objectives">

  <h2>Overview</h2>



  <div class="row">

    <div class="col-md-3">

      <strong>Teaching:</strong> 5 min

      <br/>

      <strong>Exercises:</strong> 0 min

    </div>

    <div class="col-md-9">

      <strong>Questions</strong>

      <ul>

	

	<li><p>How can lesson formatting be checked?</p>

</li>

	

	<li><p>How can lessons be previewed?</p>

</li>

	

      </ul>

    </div>

  </div>



  <div class="row">

    <div class="col-md-3">

    </div>

    <div class="col-md-9">

      <strong>Objectives</strong>

      <ul>

	

	<li><p>Run the lesson checking script and interpret its output correctly.</p>

</li>

	

	<li><p>Preview a lesson locally.</p>

</li>

	

      </ul>

    </div>

  </div>



</blockquote>



<p>The lesson template comes with several utilities to simplify lesson development and maintenance.</p>



<h2 id="checking">Checking</h2>



<p>The template includes a Python program to check

whether lesson files conform to our template.

You can run this using <code class="highlighter-rouge">make lesson-check</code>,

which in turn invokes <code class="highlighter-rouge">bin/markdown_ast.rb</code> to parse Markdown files

and <code class="highlighter-rouge">bin/lesson_check.py</code> to check their structure.

The former is written in Ruby,

and uses Jekyll’s own Markdown parser (called Kramdown)

so that we are guaranteed to be checking the same dialect of Markdown that Jekyll uses on GitHub.

The latter is written in Python 3,

and executes all of the checks.</p>



<p>The template also includes <code class="highlighter-rouge">bin/repo_check.py</code>,

which can be invoked by running <code class="highlighter-rouge">make repo-check</code>.

This program looks in <code class="highlighter-rouge">_config.yml</code> to find the repository’s URL,

then checks that the repository has the right labels set up for issues and pull requests.

Other checks will be added as time goes by.</p>



<h2 id="previewing">Previewing</h2>



<p><a href="https://jekyllrb.com/">Jekyll</a> can be used in two ways:

to compile source files into HTML pages in the <code class="highlighter-rouge">_site</code> directory,

or to do that and also run a small web server at <a href="http://0.0.0.0:4000/">http://0.0.0.0:4000/</a>

so that the pages can be previewed.

We recommend using the latter,

since it gives a more accurate impression of what your lesson will actually look like.</p>



<p>The Makefile in the root directory of the project contains commands for building the site.

<code class="highlighter-rouge">make site</code> builds files but does not run a server,

while <code class="highlighter-rouge">make serve</code> builds the files and runs a server.

(It also re-builds the site whenever it notices changes in the source files.)

Run <code class="highlighter-rouge">make</code> on its own to get a full list of commands.</p>



<p>In order to use Jekyll and/or the checking script,

you may need to install it and some other software.

The <a href="../setup/">setup instructions</a> explain what you need and how to get it.</p>



<h2 id="displaying-figures">Displaying Figures</h2>



<p>The command <code class="highlighter-rouge">make lesson-figures</code> uses the script <code class="highlighter-rouge">bin/make_figures.py</code>

to regenerate <code class="highlighter-rouge">includes/all_figures.html</code>,

which links to every figure used in the episodes (in order).

Instructors can scroll through this page to display figures while teaching.</p>







<blockquote class="keypoints">

  <h2>Key Points</h2>

  <ul>

    

    <li><p>Lessons are checked by running <code class="highlighter-rouge">make lesson-check</code>.</p>

</li>

    

    <li><p>The checker uses the same Markdown parser as Jekyll.</p>

</li>

    

    <li><p>Lessons can be previewed by running <code class="highlighter-rouge">make serve</code>.</p>

</li>

    

  </ul>

</blockquote>



</article>



<div class="row">

  <div class="col-md-1">

    <h3>

      

      <a href="../04-formatting/"><span class="glyphicon glyphicon-menu-left" aria-hidden="true"></span><span class="sr-only">previous episode</span></a>

      

    </h3>

  </div>

  <div class="col-md-10">

    

  </div>

  <div class="col-md-1">

    <h3>

      

      <a href="../06-rmarkdown-example/"><span class="glyphicon glyphicon-menu-right" aria-hidden="true"></span><span class="sr-only">next episode</span></a>

      

    </h3>

  </div>

</div>





      

      

<footer>

  <div class="row">

    <div class="col-md-6" align="left">

      <h4>

	Copyright &copy; 2016–2017

	

	<a href="https://software-carpentry.org">Software Carpentry Foundation</a>

	

      </h4>

    </div>

    <div class="col-md-6" align="right">

      <h4>

	

	<a href="/edit/gh-pages/_episodes/05-checking.md">Edit on GitHub</a>

	

	/

	<a href="/blob/gh-pages/CONTRIBUTING.md">Contributing</a>

	/

	<a href="/">Source</a>

	/

	<a href="/blob/gh-pages/CITATION">Cite</a>

	/

	<a href="mailto:lessons@software-carpentry.org">Contact</a>

      </h4>

    </div>

  </div>

</footer>



      

    </div>

    

<script src="../assets/js/jquery.min.js"></script>

<script src="../assets/js/bootstrap.min.js"></script>

<script src="../assets/js/lesson.js"></script>

<script>

  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){

  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),

  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)

  })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-37305346-2', 'auto');

  ga('send', 'pageview');

</script>



  </body>

</html>