fix formatting + add biblio

01-conceptual-elements.Rmd

@@ -4,8 +4,7 @@
 
 Carpentries curricula are developed based on the results of research in the science of
 teaching and learning. We rely on findings synthesized in the book 
-[How Learning Works: Seven Research-Based Principles for Smart Teaching](https://www.wiley.com/en-us/How+Learning+Works%3A+Seven+Research+Based+Principles+for+Smart+Teaching-p-9780470484104)
-(Ambrose et al., 2010). We use this text in our Instructor Trainer training program, so that
+[How Learning Works: Seven Research-Based Principles for Smart Teaching](https://www.wiley.com/en-us/How+Learning+Works%3A+Seven+Research+Based+Principles+for+Smart+Teaching-p-9780470484104) [@ambrose2010learning]. We use this text in our Instructor Trainer training program, so that
 Trainers (who teach our Instructor Training courses) can understand why we teach the way we
 do, and why our lessons are designed the way they are.
 
@@ -139,16 +138,16 @@ own data.
 
 Our primary aim in a Carpentries workshop is to increase the confidence of our learners. We
 want to demystify and make accessible the process of computing and analyzing data. More than
-a third of learners at our workshops have little to no coding experience ([Jordan et al., 2018](https://zenodo.org/record/1325464#.XF39ts9Kjw4)). Our workshops provide them an
+a third of learners at our workshops have little to no coding experience [@jordan2018assessment]. Our workshops provide them an
 opportunity to try, in a friendly environment, something they perceive as intimidating.
 
-Another important goal is to make the research life of our learners easier. We emphasize
-teaching "good enough practices" [(Wilson, et al., 2017)](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1005510) - 
-concrete skills that are accessible, able to be adopted by researchers of any skill level,
-and likely to make an immediate positive impact on learners' work. Teaching defensive
-programming, how to use spreadsheets effectively, or how to organise files consistently
-across research projects, are practical skills that can save a lot time when learners apply
-them in their own research.
+Another important goal is to make the research life of our learners easier. We
+emphasize teaching "good enough practices" [@wilson2017goodenough] - concrete
+skills that are accessible, able to be adopted by researchers of any skill
+level, and likely to make an immediate positive impact on learners' work.
+Teaching defensive programming, how to use spreadsheets effectively, or how to
+organise files consistently across research projects, are practical skills that
+can save a lot time when learners apply them in their own research.
 
 When developing a new curriculum, the first step is to identify the skills that will be the
 most immediately useful to learners and have the biggest impact on their work. This will 
@@ -157,7 +156,7 @@ stage.
 
 We will discuss in detail the process of defining your 
 audience and identifying these core skills for your lesson
-in [a later chapter](https://carpentries.github.io/curriculum-development/how-to-decide-what-to-teach.html).
+in [a later chapter][Deciding what to teach].
 
 ### Designing challenges to assess understanding
 
@@ -179,7 +178,7 @@ To this end, Carpentries workshops are designed to provide frequent opportunitie
 helpful in providing useful feedback, these challenges need to both a) be narrowly targeted to the skills 
 that have been taught (i.e. not to depend on untaught concepts) and b) be diagnostic (Instructors should be
 able to tell what the learner is misunderstanding based on how they answer the question). The practical 
-aspects of creating useful challenge problems is discussed in [a later chapter](https://carpentries.github.io/curriculum-development/assembling-the-lesson.html#designing-challenges). 
+aspects of creating useful challenge problems is discussed in [a later chapter][Designing challenges].
 
 ### Planning the content of the lesson
 
@@ -190,7 +189,7 @@ This material can be thought of as the "script" for the
 instructor to follow while teaching and should be planned
 very carefully to complement the exercises you've already
 designed. We cover the process of creating curricular content
-in [a later chapter](https://carpentries.github.io/curriculum-development/learning-objectives-and-formative-assessment.html).
+in [a later chapter][Developing content]
 
 ## Creating a narrative and selecting a dataset 
 
@@ -204,17 +203,19 @@ through data cleaning, analysis, and visualisation or reporting.
 It is important to choose a dataset that is an authentic 
 representation of what your audience would encounter in their
 day-to-day work. The practicalities of chosing an appropriate 
-dataset are covered in a [later section](https://carpentries.github.io/curriculum-development/assembling-the-lesson.html#picking-a-dataset) of this handbook.
+dataset are covered in a [later section][Picking a dataset]
+of this handbook.
 
 ## Limitations of our approach
 
 Learners can't go from complete novices to experts in two days (or 
 in the course of any single class). We aim to provide learners with 
-three things:  
-1) A set of foundational concepts and skills,  
-2) A mental model that connects those concepts into a useful
-framework and that can be built upon in their future learning, and  
-3) The motivation and skillset they need to continue learning 
+three things:
+
+1. A set of foundational concepts and skills;
+1. A mental model that connects those concepts into a useful
+framework and that can be built upon in their future learning; and
+1. The motivation and skillset they need to continue learning 
 past the end of the workshop. 
 
 Managing learners' expectations, and clearly communicating to 

02-what-to-teach.Rmd

@@ -27,21 +27,26 @@ following questions. Write down your answers and see if you can clearly articula
 in your audience. Share these thoughts with your colleagues and see if they agree. 
 
 ### Audience definition questions
-* What is the expected educational level of your audience? - Do you expect most learners to be undergraduate 
-students, graduate students, or to have completed graduate school? If you are targeting graduate students, 
-do you expect learners to be new graduate students, masters degree holders, or doctoral candidates?
-
-* What type of exposure do your audience members have to the technologies you plan to teach? - Think about the
-typical course work that someone in your field has completed when they are at your targeted educational level. 
-Have they had classes where they needed to use R, Python, or some other programming language for their homework?
-Does your department require any courses on data organization or management? Do students in your field 
-ever interact with a remote computing system? Don't worry if the answer to all of these questions is "no", 
-most university departments don't build computational training into their undergraduate or graduate programs - 
-which is why The Carpentries exists! Talk with others in your field, especially colleagues at different
-institutions and in different countries. Having an accurate picture of your target audience's actual exposure 
-to these skills will help you plan a realistic curriculum.
-
-* What types of tools do they already use? - Related to the previous question, it is useful to understand 
+
+* **What is the expected educational level of your audience?** -- Do you expect most learners to be undergraduate students, graduate students, or to have completed graduate school?
+If you are targeting graduate students, 
+do you expect learners to be new graduate students,
+masters degree holders, or doctoral candidates?
+
+* **What type of exposure do your audience members have to the technologies you
+plan to teach?** -- Think about the typical course work that someone in your field
+has completed when they are at your targeted educational level. Have they had
+classes where they needed to use R, Python, or some other programming language
+for their homework? Does your department require any courses on data
+organization or management? Do students in your field ever interact with a
+remote computing system? Don't worry if the answer to all of these questions is
+"no", most university departments don't build computational training into their
+undergraduate or graduate programs - which is why The Carpentries exists! Talk
+with others in your field, especially colleagues at different institutions and
+in different countries. Having an accurate picture of your target audience's
+actual exposure to these skills will help you plan a realistic curriculum.
+
+* **What types of tools do they already use?** -- Related to the previous question, it is useful to understand 
 the toolkit that your target audience is already comfortable with. Do they commonly use spreadsheet software 
 like Microsoft Excel, Numbers, or Google Sheets? Are they most comfortable working in rich text editors like 
 Microsoft Word or Google Docs? Do they use any web-based GUIs or databases? Having this information will help you
@@ -51,7 +56,7 @@ enthusiastic a new doctoral student might be about using Python, if everyone els
 their advisor) uses MatLab, they're unlikely to be successful in convincing the entire lab to change their
 workflows.
 
-* What are the pain points they are currently experiencing? - The Carpentries trainings are designed to 
+* **What are the pain points they are currently experiencing?** -- The Carpentries trainings are designed to 
 meet learners where they are and help them improve their workflows in a way that is immediately useful for them.
 We avoid idealism in favor of realism. Yes, it would be excellent if use of version control was standard 
 across the research community, but if the learners at your workshop don't see the immediate benefit of version 
@@ -61,7 +66,7 @@ back from the publisher? What repetitive tasks do they do by hand and find mista
 People love to share stories like this and you can learn a lot about what others in your field are struggling with
 by collecting these stories. These are the skills you should be targeting in your lesson. 
 
-* What types of data does your target audience work with? What are the commonalities in the datasets your target audience will encounter? (types of variable, size, standard data formats, etc.) - If you're designing
+* **What types of data does your target audience work with? What are the commonalities in the datasets your target audience will encounter?** (types of variable, size, standard data formats, etc.) - If you're designing
 a domain-specific curriculum, you'll need to consider the range of data types that members of your domain 
 community work with. For example, researchers in the social sciences work with a wide range of data types, but
 survey data is common in this research community. Data Carpentry elected to develop lessons around closed-ended
@@ -101,7 +106,7 @@ starting and ending points for your lesson. The background knowledge and skills
 to the workshop define the starting point, while your learners' goals define the end point. With these
 start and end points, you can now define the list of skills that you will need to teach at your workshop. 
 
-### Example using a Software Carpentry Learner Profile
+## Example using a Software Carpentry Learner Profile
 
 The following example illustrates how a learner profile can be used to define a list of
 concrete skills. 
@@ -169,9 +174,9 @@ An (incomplete) list of target skills that can be extracted from this informatio
 It is important at this stage to be sure you are defining **skills** that your
 learners will acquire, not **topics** that you will teach. You may be tempted to
 say, for example, that learners will learn about the [grammar of
-graphics](https://vita.had.co.nz/papers/layered-grammar.html) - which places the
+graphics](https://vita.had.co.nz/papers/layered-grammar.html) -- which places the
 emphasis on a **topic** that learners will learn **about** - or that they will
-learn how to use the [R package ggplot2](https://ggplot2.tidyverse.org/) - which
+learn how to use the [R package ggplot2](https://ggplot2.tidyverse.org/) -- which
 emphasizes the **tool** that learners will be exposed to. Neither of these ways
 of stating the learning goal focuses on the **abilities** that learners will
 develop that will help them in their work. Since you, as the lesson developer,

03-designing-challenges.Rmd

@@ -285,12 +285,13 @@ application of fill-in-the-blank problems:
 > $ mv ___/sucrose.dat  ___/maltose.dat ___
 > ```
 >
-> > ### Solution {-}
->> ```{bash, eval=FALSE}
->> $ mv ../analyzed/sucrose.dat ../analyzed/maltose.dat .
->> ```
->> Recall that `..` refers to the parent directory (i.e. one above the current directory)
->> and that `.` refers to the current directory.
+> ### Solution {-}
+> ```{bash, eval=FALSE}
+> $ mv ../analyzed/sucrose.dat ../analyzed/maltose.dat .
+> ```
+>
+> Recall that `..` refers to the parent directory (i.e. one above the current
+> directory) and that `.` refers to the current directory.
 
 
 We can also apply this concept to our earlier example and ask learners to fill-in-the-blanks
@@ -349,18 +350,18 @@ They are then asked to create a barchart showing the number of observations in e
 > create a `bar`-plot that counts the number of records for each plot. (Check
 > the documentation of the bar geometry to handle the counts)
 >
->> ### Answers {-}
->>
->> ```{python, eval=FALSE}
->> (p9.ggplot(data=surveys_complete,
->>            mapping=p9.aes(x='plot_id'))
->>     + p9.geom_bar()
->> )
->> ```
->>
->> ```{r, echo=FALSE}
->> knitr::include_graphics("./figures/python_barplot_example.png")
->> ```
+> ### Answers {-}
+>
+> ```{python, eval=FALSE}
+> (p9.ggplot(data=surveys_complete,
+>            mapping=p9.aes(x='plot_id'))
+>     + p9.geom_bar()
+> )
+> ```
+>
+> ```{r, echo=FALSE}
+> knitr::include_graphics("./figures/python_barplot_example.png")
+> ```
                      
                       
 To answer this problem, learners need to locate and decipher the appropriate help file (for

04-developing-content.Rmd

@@ -4,7 +4,7 @@ At this point in the lesson development process, you should have a list of the c
 will teach, along with a set of exercises that you will incorporate into your lesson. If you've taken the time 
 to go through these steps, the remaining parts of the development process will be much more straightforward
 and take less time than if you try to start with developing content. Its ok if your list of skills and set
-of exercises changes a little as you develop your lesson content - none of us get it right on the first try -
+of exercises changes a little as you develop your lesson content -- none of us get it right on the first try --
 however, if you've invested time in the first two steps of the backward design process,
 these changes should be fairly small.
 
@@ -14,34 +14,44 @@ here on the bare minimum you need to know to get started. It's perfectly ok to w
 steps described in this chapter before worrying about the logistics of putting your materials up on GitHub, 
 but if you're working with multiple authors, it may be worth putting your materials on GitHub at this stage,
 to make collaboration easier. The [Technological Introductions](https://carpentries.github.io/curriculum-development/technological-introductions.html) chapter
-can get you started with hosting your lesson on GitHub.  
+can get you started with hosting your lesson on GitHub.
 
 ## Fundamental elements
 
-The bulk of a Carpentries lesson consists of exercises, example code chunks, and narrative text. You have already
-developed many or all of the exercises you will include in your lesson, so congratulations on being one-third
-done with content development! The remaining two major components of the lesson are described below. 
+The bulk of a Carpentries lesson consists of exercises, example code chunks, and
+narrative text. You have already developed many or all of the exercises you will
+include in your lesson, so congratulations on being one-third done with content
+development! The remaining two major components of the lesson are described
+below.
 
 ### Code chunks
-Carpentries workshops are taught using participatory
-live coding. Instructors
-type the code as they teach it and learners type along with the Instructor. For more information about how
-live coding works, and what its advantages and disadvantages are, read that section of our 
-[Instructor Training program](https://carpentries.github.io/instructor-training/14-live/index.html). The fact 
-that Carpentries workshops are taught using live coding means that much of your episode content will be 
-*code chunks* - short blocks of code that learners type along with the Instructor and evaluate on their own
-machines. 
-
-Since you already know the structure of your dataset, and already have your exercises in place, it's fairly
-straightforward to create the code chunks for your lesson. Starting with the first exercise, make a list of each
-of the commands and syntax elements that learners need to be familiar with in order to solve the exercise. For
-example, the first exercise in the Data Carpentry lesson [Introduction to the Command Line for Genomics](https://datacarpentry.org/shell-genomics/) asks learners to: 
 
-```
-Use the `-l` option for the `ls` command to display more information for each item in the directory. What is one piece of additional information this long format gives you that you don’t see with the bare `ls` command?
-```
+Carpentries workshops are taught using participatory live coding. Instructors
+type the code as they teach it and learners type along with the Instructor. For
+more information about how live coding works, and what its advantages and
+disadvantages are, read that section of our [Instructor Training
+program](https://carpentries.github.io/instructor-training/14-live/index.html).
+The fact that Carpentries workshops are taught using live coding means that much
+of your episode content will be *code chunks* - short blocks of code that
+learners type along with the Instructor and evaluate on their own machines.
+
+Since you already know the structure of your dataset, and already have your
+exercises in place, it's fairly straightforward to create the code chunks for
+your lesson. Starting with the first exercise, make a list of each of the
+commands and syntax elements that learners need to be familiar with in order to
+solve the exercise. For example, the first exercise in the Data Carpentry lesson
+[Introduction to the Command Line for
+Genomics](https://datacarpentry.org/shell-genomics/) asks learners to:
+
+> ### Challenge {-}
+>
+> Use the `-l` option for the `ls` command to display more information for each
+> item in the directory. What is one piece of additional information this long
+> format gives you that you don’t see with the bare `ls` command?
+
 
 In order to solve this challenge, learners need to know the following (in approximately reverse order): 
+
 1. That options come after the command (e.g. `ls -l` not `-l ls`).
 1. How to find the manual page for `ls` to understand the output.
 1. What the `ls` command does in its bare form. 
@@ -109,7 +119,7 @@ to quit.
 
 Narrative text should be as short as possible and should avoid discussion of edge cases or caveats. If there
 are important caveats, those can be included in a callout box (see the 
-[Technological Introductions](https://carpentries.github.io/curriculum-development/technological-introductions.html) 
+[Technological Introductions]
 chapter for formatting details of callout boxes). Only include callouts for cases a significant fraction of your
 learners will experience in their work. It's very easy to clutter the lesson and overwhelm learners. 
 
@@ -134,7 +144,7 @@ of content for both learners and Instructors. These supporting elements are lear
 framing questions. When you create your lesson repository from The Carpentries template, there will be sections
 for you to enter these supporting items for each episode. The template will extract these elements and embed 
 them in the rendered lesson webpage. For details, see the 
-[Technological Introductions](https://carpentries.github.io/curriculum-development/technological-introductions.html) chapter.
+[Technological Introductions] chapter.
 
 ### Learning objectives