diff --git a/01-introduction.md b/01-introduction.md new file mode 100644 index 000000000..6cfbb996b --- /dev/null +++ b/01-introduction.md @@ -0,0 +1,147 @@ +--- +title: Introduction +teaching: 5 +exercises: 10 +start: yes +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- Explain how trainers and participants will interact throughout the workshop. +- Summarise the main skills that will be taught in this workshop. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- What is covered in this training? +- Who are the trainers? +- Who is participating? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +**Note:** most of the content in this chapter is reproduced or adapted from +[The Carpentries Instructor Training curriculum](https://carpentries.github.io/instructor-training/01-welcome/index.html). + +::: discussion + +### Pronouns and Names + +Using correct names and pronouns (e.g. "she/her") is important to setting a tone of respect. +Learning these is hard to do quickly, so we recommend displaying it prominently during the workshop. + +In an online workshop, give everyone a moment to update their display name to reflect how they would like to be addressed. + +At an in-person event, we recommend supplying name tags and markers, +or using plain paper to create table-displayed name placards. + +Note that pronouns are personal and some participants might prefer not to share them. +Do not force people to share their pronouns. + +::: + + +## Before The Training Begins + +::: challenge + +### Getting to know each other + +If the Trainer has chosen an +[icebreaker question](https://carpentries.github.io/instructor-training/icebreakers/index.html), +participate by writing your answers in the Etherpad. + +::: + +## Code of Conduct + +To make clear what is expected, +everyone participating in The Carpentries activities is required to abide by our +[Code of Conduct](../CODE_OF_CONDUCT.md). +Any form of behaviour to exclude, intimidate, +or cause discomfort is a violation of the Code of Conduct. +In order to foster a positive and professional learning environment we encourage you to: + +* Use welcoming and inclusive language +* Be respectful of different viewpoints and experiences +* Gracefully accept constructive criticism +* Focus on what is best for the community +* Show courtesy and respect towards other community members + +If you believe someone is violating the Code of Conduct, +we ask that you report it to The Carpentries Code of Conduct Committee +by completing [this form](https://goo.gl/forms/KoUfO53Za3apOuOK2). + +::: discussion + +### Today's Trainers + +To begin class, each Trainer should give a brief introduction of themselves. + +(For some guidelines on introducing yourself, see +[the _Workshop Introductions_ section of the Instructor Training curriculum](https://carpentries.github.io/instructor-training/23-introductions/index.html)). +::: + +Now, we would like to get to know all of you. + +:::::::::::::::::::::::::::::::::::::: challenge + +## Our First Exercise (10 minutes) + +What was the best lesson you ever followed +(were taught in a class, read through online, read in a book)? +Try to differentiate between **what was good about the performance** of the teacher/trainer +and **what was good about the content** of the lesson itself. +Take a few minutes to write down some notes about your answer, +then introduce yourself to the other participants and tell them about it. + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +## Collaborative Lesson Development Training Overview + +The main objective of this training is to teach you the skills you need to +design and develop an effective lesson, in collaboration with other members of the community. +During the training, +we will introduce the steps you can take to design and develop a lesson +to meet the needs of your target audience, +and give you time to begin implementing those steps during the workshop itself. + +We will focus on three main areas: + +### Designing a Lesson + +Much of the training will discuss a process to incorporate good practices in lesson design. +We will explore how defining the specific skills you wish to teach +early on in the development process +provides a foundation from which you can build a stronger, more impactful lesson. + +### Building a lesson website + +Throughout the training, while you design and begin developing the content of your lessons, +we will teach you how to incorporate this into an organised and accessible website +using our lesson infrastructure. + +### Collaborating effectively + +We believe that lessons are much more likely to succeed, and to remain useful in the long term, +if they are developed collaboratively. +This training will discuss some of the ways that you can welcome new collaborators +and work effectively and efficiently with those you already have. + +### Learning how to teach a lesson + +This training will focus on the content - how to prepare a good lesson. +More about the performance - how to deliver a lesson most effectively - +is covered in +[The Carpentries Instructor Training](https://carpentries.github.io/instructor-training/). + + + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- This training aims to teach you a process for designing and developing a lesson website, in collaboration with others. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + diff --git a/02-lessons.md b/02-lessons.md new file mode 100644 index 000000000..e7e9be58e --- /dev/null +++ b/02-lessons.md @@ -0,0 +1,48 @@ +--- +title: Your lessons +teaching: 0 +exercises: 10 +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- Summarise the lessons that participants will be working on. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- What lesson do you want to develop during and after this workshop? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +This training will provide many opportunities for discussion of your lessons. +Providing some context now for the lessons that you will be creating will +help the Trainers and other participants get involved in those discussions +and give you feedback as you follow the process. + +::::::::::::::::::::::::::::::::::::: discussion + +## Discussion (10 minutes) + +Take a few minutes to think about your answers to the following questions: + +1. What is the topic of the lesson that you plan to develop based on this training? +2. Have you created training material on this topic before? +3. What is motivating you to create this lesson? + +Make some notes, then share a single-sentence answer to each question with the other participants. + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- There can be many reasons to create a new lesson. +- This training will give you a process to follow to ensure your lesson is effective. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + diff --git a/03-audience.md b/03-audience.md new file mode 100644 index 000000000..fd338acec --- /dev/null +++ b/03-audience.md @@ -0,0 +1,261 @@ +--- +title: Identifying your target audience +teaching: 25 +exercises: 20 +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- Describe the importance of aligning lesson design with the intended audience. +- Compose a list of prior knowledge required to follow a lesson. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- What are the recommended steps to take when developing a new lesson? +- Why is it so important to think about the target audience early in the process? +- How can you ensure that your lesson reaches the right audience? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +## A Lesson Design Process + +In the next parts of this training, +we will use a modified version of Nicholl's five phase paradigm for curriculum design [[1][f1000-course-design-guide]]. +Nicholl's paradigm describes a process, commonly referred to as _backward design_, +where those who wish to develop a new curriculum first begin by defining +exactly what their learners will be able to do +_after they have completed the lesson/training/course_. +The subsequent stages of the curriculum design process involve designing content +to directly meet those stated outcomes. + +1. Select learning outcomes +2. Choose learning experiences to help learners achieve these outcomes +3. Develop content to support these experiences +4. Assess learner progress towards desired outcomes +5. Evaluate chosen outcomes, experiences, and content based on this assessment + +**TODO: add a figure illustrating the setps in the list above. +could be based on Fig. 2 in [f1000-course-design-guide]** + +The last two phases of Nicholl's paradigm involve +assessing learner progress towards the desired learning outcomes and +evaluating the stated objectives and current content in light of the results of that assessment. +In The Carpentries, most workshops are relatively short-format, +without room for an extensive assessment after the teaching has finished +(a _summative_ assessment). +To account for this, our lessons place an emphasis on _formative_ assessment: +assessment of learner progress that takes place _while the teaching is still going on_, +to give instructors opportunities to evaluate the teaching and lesson content +before the end of the workshop. + + +To account for this, +we have adapted Nicholl's five phases in this training, +to place an emphasis on assessing learning during a workshop: + +1. Define desired learning outcomes +2. Decide with what activities/examples/explanations we will try to teach these skills +3. Create assessments to determine progress towards desired outcomes +4. Write content to lead learners from one of these assessments to the next +5. (After the break) evaluate how closely the outcomes meet the objectives + +**TODO: add a figure illustrating the process described in the list above. +could be similar to the one used earlier for Nicholl's original list.** + +## Target Audience + +Given the limited time in a short-format training, +it is vital to define the scope of the lesson i.e. +what people will know before and after the lesson. +Thinking carefully about the target audience will help with this. +Prominently displaying a description of the target audience +will also help attract people with the right motivation and +relevant prior knowledge to attend your workshops. + +### Expertise + +One of the most important things we can identify about our target audience +is the level of expertise they will already have in relation to the skills taught by your lesson. +In The Carpentries Instructor Training curriculum, +we describe +[three different stages of skill acquisition: novice, competent practitioner, and expert][it-skill-acquisition] and how it directly correlates to the complexity of [mental models][it-mental-models] these different groups have about a domain/topic. + +Briefly, the novice is someone who does not know what they do not know, i.e., they do not yet know what the key ideas in the domain are or how they relate, the competent practitioner has enough understanding of the domain/topic for everyday purposes, and the expert is someone who can easily handle situations that are out of the ordinary and can immediately use their prior knowledge or skills when presented with a new problem in the domain. + +When designing a new lesson, it is important to think about +the level of expertise that you expect learners to arrive with for two reasons: + +1. It helps to predict what prior knowledge and + [mental model][it-mental-models] learners will have + of the lesson domain when they arrive. + This can enable you to make progress quickly + by + a) working to help learners recall (_activate_) that prior knowledge, + b) building on the conceptual understanding they already have and, + c) perhaps most importantly, + giving you some idea of what _misconceptions_ they might arrive with. + It is vital that misconceptions are identified and corrected early on, + before learners try to incorporate new knowledge into a broken mental model. +2. People at different stages of this process need to be taught differently. + For example, novices will learn more from lessons that include worked examples + and are more tutorial-like i.e. focused on a specific task, + with step-by-step explanations of the process, + but without a lot of extra information that is not directly relevant. + However, the same approach may actually hinder learning for competent practitioners + who may be distracted by a step-by-step explanation + of something they already have the prior knowledge to understand on their own. + For learners at this level of expertise, + lessons which include activities offering learners + the freedom to explore options and develop their own solutions, + are likely to be more effective. + +### Motivation + +Furthermore, your lesson will be more effective if +it aligns with the motivations of the target audience. +Understanding the wants and needs of your target audience, +what they know already and what kinds of problems they want to solve, +will help you design a lesson that learners can see the value in. +It will give them the impression that taking the lesson will be worthwhile +(called _positive expectancies_ in the literature). + +We will look more at strategies to establish value and build positive expectancies +in the next chapter. + +### Be Specific + +It can be tempting to identify a target audience only in vague terms, +for example by writing that a lesson is aimed at +"PhD students" or "early career researchers". +However, +taking the time to focus on real people, +or imagined personae, +who represent your target audience will help you take time to consider +the various aspects that can influence how much someone will learn from your lesson. +It will also help you notice when the assumptions you are making about your target audience +are unreasonable. + +Most of all, it will help you stay connected to the fact that +_you are not your learners_: +they will arrive at the lesson with different priorities, +interests, and challenges than your own. + +:::::::::::::::::::::::::::::::::::::: challenge + +## Exercise: thinking about target audience (15 minutes total for both parts) + +Part 1 (5 minutes): think about a member of the target audience for your lesson, +and answer the following questions in the context of your lesson topic: + +1. What is their background? +2. What do they already know how to do? +3. What do they want to do with the skills they will learn from your lesson? +4. What problem will your lesson help them solve? + + +:::::::::::::: solution + +## Part 2a (for groups collaborating on the same lesson, 10 minutes) + +Share your answers with your collaborators. How do they compare? +If you have identified different audiences, are they compatible? +Or would your time be better spent focussing on one particular audience for this lesson? + + +::::::::::::::::::::::::: + +:::::::::::::: solution + +## Part 2b (for participants developing their lesson alone, 10 minutes) + +Write 1-2 diagnostic questions, for use before the lesson is taught, +to help you assess whether a respondent falls within the intended audience for your lesson. + + + +::::::::::::::::::::::::: + + + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + +::::::::::: callout + +## Thinking more about target audience + +There is more to consider about your target audience than we could capture +with only the questions listed above. +In your own time, you should think more about the +other considerations you might need to make when writing a lesson for +your audience. + +For example, what vocabulary do they use? +The terms you are teaching in your lesson might have a different meaning +in your learners' domain of expertise, +and it can be helpful to prepare for and try to avoid confusion arising from this clash. +Furthermore, might their primary language differ from yours? +If so, how might this change the way you write the lesson? + +::::::::::::::::::: + +## Defining Prerequisite Knowledge + +A very common challenge encountered in workshops is +heterogeneity of expertise among the audience. +When learners arrive at a workshop with +a wide range of previous experience with the topic, +it is difficult for the instructors to keep everyone engaged. +Those who arrive with too little relevant knowledge and experience +can struggle to follow the lesson content at the pace you expect, +while those who arrive with too much are likely to become bored +and despondent as their expectation of learning new skills is not met. + +One way to try to guard against this is to publish +the description of your target audience when you advertise a workshop teaching your lesson, +alongside a list summarising the skills and conceptual knowledge +you expect learners to arrive with. +Another is to use the information you have about your target audience +to ask questions of potential learners when they apply/register to join the workshop +(like the diagnostic questionnaire you may have prepared in the exercise above), +and use the answers they give to filter out those who fall outside +your intended audience. + +While valuable, this kind of pre-assessment should be approached +with caution: +[people are often bad at self-assessment i.e. estimating our own ability to perform a task][hacker-2000]. +We can try to mitigate for this when designing the questions for a pre-workshop survey, +leaving little room for inaccurate self-assessment to confound the results. +But experience suggests it is very difficult to ensure that +every learner in a workshop falls within the intended audience of a lesson. + +:::::::::::::::::::::::::::::::::::::: challenge + +## Exercise: defining prerequisite knowledge (5 minutes) + +Write a list of the skills/knowledge your learners will be required to have +before they can follow your lesson. + +If you are struggling with this exercise because your lesson audience is novices, +think about skills like touch typing, using a web browser, or interacting with a command line +or graphical interface. +These are skills commonly overlooked by experts and competent practitioners. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + +[f1000-course-design-guide]: https://f1000research.com/documents/9-1377 +[it-mental-models]: https://carpentries.github.io/instructor-training/02-practice-learning/index.html#building-a-mental-model +[it-skill-acquisition]: https://carpentries.github.io/instructor-training/02-practice-learning/index.html#the-acquisition-of-skill + + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- First key point. Brief Answer to questions. (FIXME) + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + diff --git a/04-short-break.md b/04-short-break.md new file mode 100644 index 000000000..64981b494 --- /dev/null +++ b/04-short-break.md @@ -0,0 +1,12 @@ +--- +title: Break +teaching: 0 +exercises: 0 +break: 15 +--- + +Take a break. If you can, move around and look at something away from your screen to give your eyes a rest. + + + + diff --git a/05-objectives.md b/05-objectives.md new file mode 100644 index 000000000..9bb8f4729 --- /dev/null +++ b/05-objectives.md @@ -0,0 +1,271 @@ +--- +title: Defining lesson objectives/outcomes +teaching: 30 +exercises: 50 +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- Explain the importance of defining specific, measurable, attainable, relevant and time-bound objectives for a lesson. +- Evaluate a written lesson objective according to these criteria. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- How can describing the things you intend to teach aid the process of writing a lesson? +- How can you be specific and realistic about what you will teach in your lesson? +- What are some of the risks associated with unrealistic or undefined expectations of a lesson? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + +At this stage of the training, +you should have a clear idea of who the target audience is for your lesson, +and what knowledge, skills, and abilities you expect them to arrive with. +Now it is time to consider the additional knowledge, skills, and abilities they will have +by the time they leave: +these are the _learning outcomes_ of your lesson. +It can feel strange to jump from one end of the process to the other like this, +but clearly defining your goals early in the lesson development process is vital. +As we will see in this chapter, +it helps you to determine the activities, examples, etc +that are appropriate for the lesson content, +and provides a scope for what should and should not be included. + + +## Why focus on skills? + +To ensure your audience stays motivated, and your lesson feels relevant to them, +we recommend that lessons focus on teaching skills rather than tools. +Lessons should be centred around what you are empowering learners to _do_, +what will be most beneficial to them, +rather than a list of functions or commands you are teaching them to use. +Placing the emphasis on skills over tools will help you prioritise key concepts +and consider how your lesson can have the biggest impact on the way learners do their work. + + +## Learning objectives + +The desired outcomes (the _learning objectives_) of a lesson should be new skills, +i.e. things that the learner can do. +For the vast majority of lessons, +these will be _cognitive skills_: things learners can do with their minds. +(Lessons intended to teach other kinds of skill, +such as woodwork, +playing a musical instrument, +or making sushi, +are probably better suited to a different platform than a static website.) +Cognitive skills cannot be equally easily acquired: +before we can apply concepts and create something new, we must attain the ability to remember +and distinguish between new concepts. +Remembering and distinguishing are also abilities that are often faster to gain then applying or creating. + +We must try to be realistic about how far along this scale we can move learners during a single workshop/lesson. +This is one reason why the target audience is so important: +if we can predict what learners will know when they arrive at the lesson, +we can better define the outcomes we can expect when they leave. + +Defining objectives for a lesson is essential because it allows us to focus the +rest of our time on developing content that is necessary for learners to reach these goals. +It will help us ensure we do not miss anything important or, conversely, +include anything superfluous that could use up valuable time or distract instructors and learners. + + +## What does an objective look like? + +Objectives can be defined for a lesson as a whole - +what should learners be able to do at the end of a workshop teaching this lesson? - +and for individual sections within it - +what should learners be able to do after following this particular part of the lesson? +The objectives for the current section of this training are: + +::::::::: checklist + +## Objectives for this section + +- Explain the importance of defining specific, measurable, attainable, relevant and time-bound objectives for a lesson. +- Evaluate a written lesson objective according to these criteria. + +:::::::::::::::::::: + +These should be read as if they were endings to a sentence beginning + +> "At the end of this session, learners should be able to ..." + +Each objective starts with a verb and describes one (and only one) skill the learner will obtain. + +For objectives to be as helpful as possible, +they need to be written in a way that will allow us to directly observe whether +or not a learner has attained the skills we want them to. +This means that the skills described by our objectives should be measurable: +as a general rule, action verbs such as "explain," "choose," or "predict," +are more helpful than passive verbs such as "know," "understand," or "appreciate", +which are hard to directly assess and are often open to interpretation. + +A popular aid for defining learning objectives is [Bloom's Taxonomy][blooms], +which divides cognitive skills into several categories. +The original taxonomy arranged these categories in a strict hierarchy, +which has since been disputed. +Regardless of whether these skills conform to such a hierarchy, +the Taxonomy serves as a very useful bank of action verbs for use +in learning objectives. + +We will see how helpful it can be to use action verbs in learning objectives +when we begin talking about exercise design in the coming chapters. + + +## SMART objectives + +To assist you in defining and writing learning objectives for your lesson, +it can be helpful to turn to a popular framework for defining goals: _SMART_. + +SMART objectives should be: + +- **S**pecific: they should clearly describe a particular skill or ability the learner should have. +- **M**easurable: it should be possible to observe and ascertain when the learner has learned the skill/abilities described in the objectives. +- **A**ttainable: the learner should realistically be able to acquire the skills or abilities in the time available in a workshop/by following the text of the lesson. +- **R**elevant: they should be relevant to the overall topic or domain of the lesson as a whole. +- **T**ime-bound: they should include some timeframe within which the goal will be reached. For learning objectives, this is built into the approach described above. + + + +:::::::::::::::::::::::::::::::::::::: challenge + +## Exercise: evaluating learning objectives (15 minutes) + +Look at the example learning objectives below. +Fill in the table for each objective, +checking off the cells if you think an objective +meets the criteria or leaving it unchecked if not. +You should assume each objective is for a lesson to be taught in a two-day workshop. +Note down any observations you make as you move through the list. +If you have time, +try to imagine the titles of lessons that would have these objectives. +This part of the exercise should take 10 minutes. + +_At the end of this lesson, learners will be able to:_ + +1. create formatted page content with Markdown. +1. program with Rust. +1. fully understand GitHub Actions. + +| Objective | Action verb? | Specific | Measurable | Attainable | +|-----------|--------------|----------|------------|------------| +| 1 | | | | | +| 2 | | | | | +| 3 | | | | | + +In the last five minutes of the exercise, +we will discuss as a group how each objective might be improved. + +::: solution + +| Objective | Action verb? | Specific | Measurable | Attainable | +|-----------|--------------|----------|------------|------------| +| 1 | :white_check_mark: | :question: | :question: | :white_check_mark: | +| 2 | :question: | :x: | :x: | :question: | +| 3 | :x: | :x: | :x: | :question: | + +Objective 1 is the closest to what we ideally want in a lesson objective, +but it illustrates how difficult it can be to make an objective truly specific. +For example, a more specific and measurable version of this objective could be: + +> _write links, headings and bold and italicised text with Markdown._ + +:::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + +## Lesson scope + +One of the major challenges of lesson design is choosing what to include in a lesson: +what the main points will be, +in what order they will be introduced, +how much detail can be provided, +and how much time can be spent on each point. +Especially when writing lessons for short form training like a Carpentries workshop, +difficult decisions often need to be made about what can and cannot be included. +[Trying to fit too much content into a lesson is counter-productive][lujan-decarlo], +so it is good to avoid the temptation to cram in more content than you +have time to cover properly. + +Writing learning objectives is a good opportunity to begin thinking about +this lesson scope, +and can provide assistance when you are faced with a difficult decision +about what content to cut out. + +For instance, consider the order in which new skills must be acquired. +Before learners can begin to acquire "higher-level" cognitive skills +to perform creative and analytical tasks, they must first acquire +the foundational knowledge and conceptual understanding of the domain. +Furthermore, these higher-level skills take longer to acquire so, +unless you can expect your target audience to arrive at the lesson +with the relevant foundational knowledge and understanding, +it is probably unrealistic to aim to have learners +completing creative tasks before its end. + +As should become clear through activities in the upcoming chapters, +lessons can be broadly considered as blocks of content associated with +a particular learning objective. +This can be helpful when making choices about content to remove, +because the task can be considered in the context of taking out whole +learning objectives. + + +## Defining learning objectives + +We have discussed the importance of defining objectives early in +the lesson design process, +and looked at some examples of objectives written for other lessons. +Now it is time to begin defining objectives for your own. + +:::::::::::::::::::::::::::::::::::::: challenge + +## Exercise: defining objectives for your lesson (20 minutes) + +Write learning objectives for your lesson - +what do you want learners to be able to do at the end of the workshop? +When writing these lesson-level objectives, +try to follow the SMART framework: +make them specific, measurable, attainable, relevant, and time-bound. + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::: challenge + +## Exercise: reviewing lesson objectives (15 minutes) + +Swap objectives written in the previous exercise with a partner +(you can also explain or show them what you wrote about your target audience, but this not essential) +and review them with the following questions in mind: + +- Are the objectives clear? +- Do they use "action" verbs? +- Could you directly observe whether a learner had reached this objective? + +Now run the objectives through [this Lesson Objective Advisor tool from the University of Manchester's Faculty of Science and Engineering](https://web.cs.manchester.ac.uk/iloadvisor/). +Do the results match your assessment? + +- Where do the skills described in these objectives sit on the scale? +- (optional) Are these objectives realistic, given the target audience of the lesson? + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + + + + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- Defining objectives for a lesson can help to focus your content on the most important outcomes, and outline the scope of the project. +- Following the SMART framework can help make your learning objectives as useful as possible. +- Leaving objectives unrealistic or undefined increases the risk of a lesson losing focus or spending time on activities that do not help learners gain the most important skills. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + +[lujan-decarlo]: https://journals.physiology.org/doi/pdf/10.1152/advan.00061.2005 diff --git a/06-long-break.md b/06-long-break.md new file mode 100644 index 000000000..8105d393d --- /dev/null +++ b/06-long-break.md @@ -0,0 +1,12 @@ +--- +title: Break +teaching: 0 +exercises: 0 +break: 60 +--- + +Take a break. If you can, move around and look at something away from your screen to give your eyes a rest. + + + + diff --git a/07-infrastructure.md b/07-infrastructure.md new file mode 100644 index 000000000..fda431433 --- /dev/null +++ b/07-infrastructure.md @@ -0,0 +1,508 @@ +--- +title: The Carpentries Workbench +teaching: 50 +exercises: 50 +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- Identify the key tools used in The Carpentries lesson infrastructure. +- Complete the fundamental setup steps for a new lesson repository. +- Edit Markdown files using the GitHub web interface. +- Define the objectives of a section within a whole lesson. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- How is a lesson site set up and published with GitHub? +- What are the essential configuration steps for a new lesson? +- How do you create and modify the pages in a lesson? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +At this stage in the training, +you should have a clear idea of who the people are that you want to teach this lesson to, +and what exactly the skills are that you want them to learn while they are following it. +It is time to begin creating a website that will present that lesson to the world! + +## GitHub Pages + +The source of all The Carpentries lessons is made publicly-available in repositories on [GitHub]. +By making our repositories public like this, +we encourage others to help us maintain and improve our lessons, +and make it as easy as possible for them to re-use and modify our lessons for their own purposes. + +GitHub provides a hosting service to open source projects such as these, +allowing users to present their projects to the wider world. +The repository includes a complete history of the changes made +between versions of the individual files in the project, +and provides many features that facilitate collaboration on projects. +We will learn more about some of those collaborative features later in this training. +For now, we will focus on one other important feature that GitHub provides: website hosting. + +Via a system called **GitHub Pages**, users can build and host websites +from the files present in any repository on GitHub. +For many years, +this has been how The Carpentries presents its lesson websites to the world. + +## Using The Carpentries Workbench + +Carpentries lesson websites are built with **The Carpentries Workbench**, +a toolkit that converts Markdown and RMarkdown files into the HTML +that can be served by GitHub Pages. +We will use it now to initialise a new lesson. + +::: callout + +### A Brief History of The Carpentries Lesson Infrastructure + +In the past, our lesson sites were generated by software called _[Jekyll]_, +a tool built into GitHub Pages that allows the webpage content, +written in the text files of the repository, +to be combined with descriptions of settings, +structure, +and styling, +to create a website. +The template used by Jekyll to structure and style lessons +was initially developed in 2013/2014 +by Abby Cabunoc Mayes, Greg Wilson, Jon Pipitone, and Michael Hansen +for [Software Carpentry][swc-home]. +It was [expanded and maintained by many members of the community][styles-contributors] +over almost a decade, +to also support [Data Carpentry][dc-home], [Library Carpentry][lc-home], and many other lessons. + +In 2022, we adopted a new infrastructure for our lesson sites: **The Carpentries Workbench**. +Lesson sites built on the Workbench are still hosted with GitHub Pages, +but no longer use Jekyll. +Instead, the lessons are built using a programming language, _[R]_, and _[pandoc]_, +a software designed for converting content between file formats. +The Workbench combines three R packages: + +- `{sandpaper}`: + converts a collection of Markdown or RMarkdown files into + the structure of a lesson website. +- `{varnish}`: provides the files and folders that add + styling and additional functionality to a lesson website. +- `{pegboard}`: an programmatic interface to the lesson, + enabling various automated validation tasks. + +For lesson developers, +the Workbench makes The Carpentries lesson repositories +much simpler to navigate and work with. + +::: + +### Creating a Lesson Repository + +To get started, we first need to create a new repository for our lesson. +We will use a template to do this, +so that the new repository contains the basic files and folders +that the Workbench needs in order to build a lesson site. +There are currently two templates to choose between: + +1. [A Markdown template][md-template] +2. [An RMarkdown template][rmd-template], best suited to lessons that will include R source code that will generate output. + +**One member of each participating lesson team** should choose one of these templates, +following the link above and completing the configuration as follows: + +* add a name for the repository + * The name should be descriptive but fairly brief, + with hyphens (`-`) to separate words + * the name can always be changed later, via the repository settings +* in the "Description" field, write the title of your lesson +* choose "Public" visibility +* make sure the "Include all branches" box is checked + +After pressing the _Create repository using this template_ button, +you should be presented with a brand new lesson repository. + +TODO insert screenshot of repository structure here + +#### Adding collaborators + +To be able to add content to the lesson, +your collaborators on this project will need access to the repository. +To add collaborators to the repository, +navigate to _Settings_, then choose _Collaborators_ from the left sidebar. +Now repeat the following steps for every collaborator working with us on the project. + +- Click _Add people_ and enter the GitHub username of one of our collaborators. +- Click _Add USERNAME to this repository_. + +Your collaborator should receive an email inviting them to join the repository. +After they have accepted this invitation, they should be able to edit the repository, +adding new files and modifying existing ones. +Only the person who created the repository will be able to adjust the repository settings. + +### Repository Files + +The repository contains a number of files and folders. +Most of these are source files for the content of our new lesson, +but a few are accompanying files primarily intended for the repository itself +rather than the lesson website. +These are: + +- `CODE_OF_CONDUCT.md` +- `CONTRIBUTING.md` +- `LICENSE.md` +- `README.md` +- `.gitignore` +- and the `.github/` folder. + +We will address all of the files later in the training. +For now, we will move on to complete the basic setup of the lesson. + +### Configuring a Lesson Repository + +#### Activating GitHub Pages + +We need to tell GitHub to begin serving the lesson website via GitHub Pages. +To do this, navigate to _Settings_, then choose _Pages_ from the left sidebar. +Under _Source_, choose the `gh-pages` branch, leave the folder set to `/ (root)`, +and click _Save_. +Now, copy the URL in the box: this will be the address of your lesson site. + +::: callout + +### Which branch to use? + +Although we configure GitHub Pages to serve the lesson website from the `gh-pages` branch, +**the default working branch for a lesson will be `main`**. +For the rest of this training, you should add and edit files on `main`, +and in future, when you open Pull Requests to update the lesson content, +these should also be made to `main`. +The `gh-pages` branch should never be modified by anyone other than the automated actions-user account. + +::: + +Returning to the repository home page +(e.g. by clicking the name of the project near the top left of the window), +click the gear wheel icon near the top right, to edit the _About_ box. +Paste the Pages URL into the _Website_ box and click _Save changes_. + +After following these steps, when you navigate to the pages URL, you should be see a lesson website with The Carpentries logo and "Lesson Title" in the top-left corner. +You may need to wait a few minutes for the website to be generated. + +#### `config.yaml` + +The lesson title can be adjusted by modifying the `config.yaml` file in the repository. +The `config.yaml` file contains several global parameters for a lesson - +to determine some of the page styling, contact details for the lesson, etc - +and is written in _[YAML]_, a structured file format of key-pair values. +As well as the title of the lesson, +you can and should adjust some of the other values in `config.yaml`, +but you should not need to add new values or learn a lot about YAML +to be able to configure your lesson. + +::: challenge + +### Practice with `config.yaml` (5 minutes) + +Complete the configuration of your lesson by adjusting the following fields in `config.yaml`: + +- `email`: add an email address people can contact with questions about the lesson/project. +- `created`: the date the lesson was created (today's date) in YYYY-MM-DD format. +- `keywords`: a (short) list of keywords for the lesson, + which can help people find your lesson when searching for resources online. +- `source`: change this to the URL for your lesson repository. + +We will revisit the `life_cycle` and `carpentry` fields in `config.yaml` later in this training. + +::: + +::: challenge + +### Improving the `README.md` (5 minutes) + +The `README.md` file is the "front page" of your lesson repository on GitHub, +and is written in Markdown. +You should use it to provide basic information about the project, +for anyone who finds their way to the source files for your lesson. +Take a few minutes to update it with some basic information about the project: + +- the lesson title +- a short description of the lesson +- a list of the names of the authors, optionally linked to their GitHub profile + +::: + + +## Adding Lesson Content + +Now that we have completed the basic configuration of a lesson site, +it is time to move on and look at where the actual lesson content will be written. + +#### Lesson Home Page + +The "home page" of a lesson is created from the `index.md` file: +this file should contain a brief introduction to the lesson, +designed to give visitors to the page a first impression of the lesson +and whether it is appropriate for them. +The file begins with a short header, +written in the same key-value pair syntax we encountered in `config.yaml`. + +```markdown +--- +site: sandpaper::sandpaper_site +--- + +``` + +This header configures how the site will be built by `sandpaper`, +one of the components of The Carpentries Workbench, +and should be left untouched. +The page content begins after the blank line that follows this header. + +To get started on this home page, +replace the template text with +the same title and short description you added to your `README.md`. + +Below those, you can add the prerequisite skills you determined earlier for your lesson, +as a bullet point list to `index.md`: + +```markdown +- prerequisite 1 +- prerequisite 2 +- ... +``` + +:::::::::::::::::::::::::::::::::::::: challenge + +## Exercise: practice editing Markdown in GitHub (optional) + +Add the objectives you defined for your lesson +as a bullet list in the `index.md` file of your lesson repository. + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +The main body of the lesson is written in _episodes_: +the individual chunks or sections that the lesson is separated into. +The episode pages of the lesson site will be constructed from Markdown files +in the `episodes` folder of the lesson repository. + +::: callout + +### Why episodes? + +TODO: add context and explanation for our use of "episodes" to describe chunks of a lesson. + +::: + +The `episodes` folder of the new repository contains a single file, +`01-introduction.md`. +The content of this file includes examples of how to write Markdown files +for The Carpentries Workbench. + +There are two important things to note: + +1. Like `index.md`, the episode file begins with a short header. + The fields in this header describe the episode title and the estimated time (in minutes) + required to teach it and complete the exercises. +2. The example content includes several lines that start with strings of colons (`:::::::`). + These mark the beginnings and ends of structural elements within the page, + called _fenced divs_. + Each fenced div starts and ends with a string of colons. + A word at the end of the starting colons indicates what kind of block it is. + We will explore them in more detail later in the training. + +Let's create a new episode file, for one of the episodes you have just identified. +First, open the "raw" view of the `01-introduction.md` example episode, +and copy the first 19 lines, +down to the blank line under the closing string of the `objectives` div. + +```markdown +--- +title: "Using Markdown" +teaching: 10 +exercises: 2 +--- + +:::::::::::::::::::::::::::::::::::::: questions + +- How do you write a lesson using Markdown and `{sandpaper}`? + +:::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::: objectives + +- Explain how to use markdown with The Carpentries Workbench +- Demonstrate how to include pieces of code, figures, and nested challenge blocks + +:::::::::::::::::::::::::::::::::::::::::::::::: +``` + +::: instructor + +Be careful here to ensure that participants who are collaborating on the same repository +do not create conflicts e.g. by editing the same file or creating files with identical names. + +::: + + +Now create a new file in the `episodes` folder and, +based on the episodes you planned out in _Defining lesson objectives_, +choose a name for it that concisely describes the intended content. +To control the order of episodes in the lesson, +the name should start with two digits, +e.g. `02-data-visualisation.md`. + +For page content, paste those first 19 lines of the `01-introduction.md` file and: + +1. replace the title +2. set the `teaching` and `exercises` fields to zero for now +3. replace the contents of the `questions` and `objectives` divs with "TODO" + + +```markdown +--- +title: "Episode Title" +teaching: 0 +exercises: 0 +--- + +:::::::::::::::::::::::::::::::::::::: questions + +- TODO + +:::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::: objectives + +- TODO + +:::::::::::::::::::::::::::::::::::::::::::::::: +``` + +:::::::::::::::::::::::::::::::::::::: challenge + +## Exercise: practice creating episodes (10 minutes) + +Repeat the steps you just saw, to create another new episode file. +If you know what another episode in your lesson will be about, +create the page for that. +Otherwise, feel free to use any values you like for the file name and episode title. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + +When these episode files have been created, +you can navigate back to the lesson website. +Refresh the page and, +under _Chapters_ in the left sidebar, +you should find the titles of all the episodes in +the `episodes` folder of your repository. +Clicking on one of those titles will take you to the episode page built from the file you created. +At the top of the page body, you will find the episode title +and an _Overview_ box containing a list of the questions and objectives +defined for the episode. +Later, we will add more content to your chosen episodes. + +TODO add a labelled screenshot of a new episode page + +Using this approach, we can build up our lesson one episode at a time. + +We have now learned everything we need to be able to use The Carpentries Workbench, +and our focus can return to the process of developing a new lesson. + +## Defining Episode Objectives + +In _Defining Lesson Objectives_, +you created a list of the learning objectives for your lesson as a whole. +This process is helpful as a way to set the end goal and, +coupled with the expected prior knowledge of the target audience you identified, +describe the scope of the lesson. + +We can use the same approach for the individual episodes of a lesson, +defining objectives for the episode to make clear what we intend to teach in that section. +Defining these objectives _before writing the episode content_ helps us to: + +- stay focused in the episode, without spending time on non-essential topics +- determine whether learners are attaining the skills we wish to teach them + (we will discuss this more in the next two episodes) +- summarise the skills the learner can expect to gain by following this section of the lesson + +::: challenge + +### Exercise: define objectives for your episode (30 minutes) + +1. Using the same approach as you did for your whole-lesson objectives, + define a set of SMART objectives for your chosen episode. (15 minutes) +1. Add this list of objectives to replace + the `TODO` in the `objectives` fenced div of your episode file (5 minutes) +1. Compare your list with those created by your collaborators on the lesson: + - are there any gaps in these objectives, + i.e. anything that should be covered in these episodes but is not captured in the objectives? + - are there any overlaps, i.e. anything that looks like it will be covered more than once? +1. As a group, discuss how you will address any problems identified in the previous step, + and edit your objectives accordingly. + +:::::: solution + +After you have defined the episode objectives, you can add them to the `objectives` div as follows: + +```markdown +::::::::::::::::::::::::::::::::::::: objectives + +- objective 1 +- objective 2 +- ... + +:::::::::::::::::::::::::::::::::::::::::::::::: +``` + +:::::: + +::: + +::: challenge + +### More Practice with Fenced Divs (optional) + +The Carpentries Workbench provides another type of fenced div, `prereq`, +that can be used to create a block highlighting the preprequisites for a lesson. + +Use one of these `prereq` fenced divs to format the list of +prerequisite skills you added to your `index.md` file earlier. + +:::::: solution + +In `index.md`: + +```markdown +:::::::::: prereq +- prerequisite 1 +- prerequisite 2 +- ... +::::::::::::::::: +``` + +:::::: + +::: + +Now that we have defined objectives for our episodes, +we can start working on the next step in developing an effective lesson: +designing exercises that will assess whether a learner has learned what you aimed to teach them. + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- First key point. Brief Answer to questions. (FIXME) + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + +[dc-home]: https://datacarpentry.org/ +[GitHub]: /~https://github.com/ +[Jekyll]: https://jekyllrb.com/ +[lc-home]: https://librarycarpentry.org/ +[md-template]: /~https://github.com/carpentries/workbench-template-md/generate +[pandoc]: https://pandoc.org/ +[R]: https://www.r-project.org/ +[rmd-template]: /~https://github.com/carpentries/workbench-template-rmd/generate +[styles-contributors]: /~https://github.com/carpentries/styles/graphs/contributors +[swc-home]: https://software-carpentry.org/ +[YAML]: https://yaml.org/ + diff --git a/08-short-break.md b/08-short-break.md new file mode 100644 index 000000000..64981b494 --- /dev/null +++ b/08-short-break.md @@ -0,0 +1,12 @@ +--- +title: Break +teaching: 0 +exercises: 0 +break: 15 +--- + +Take a break. If you can, move around and look at something away from your screen to give your eyes a rest. + + + + diff --git a/09-formative-assessment.md b/09-formative-assessment.md new file mode 100644 index 000000000..141db02b6 --- /dev/null +++ b/09-formative-assessment.md @@ -0,0 +1,103 @@ +--- +title: Stay on Target +teaching: 30 +exercises: 35 +--- + +- With learning objectives you have defined your *intended* curriculum. +- What learners leave with after the lesson/workshop (*attained* curriculum) will be a combination of *implemented* and *hidden* curriculum. + - Implemented curriculum: the concepts, relationships, and skills that are explicitly covered in your lesson. + - Hidden curriculum: the additional things, not directly addressed in the content, that people learn about the topic from your lesson/the way it is taught. + - You can use Instructor Notes to guide Instructors on some of the important hidden curriculum to consider e.g. to encourage them to model certain practices. +- [The goal of the remaining steps of lesson development is to ensure that the attained curriculum matches the intended curriculum as closely as possible](https://f1000research.com/documents/9-1377). +- Assessments are a way to determine whether the objectives you defined for the lesson/a section of the lesson have been reached + - Formative assessments during the workshop + - Summative assessments at the end. + - For short-format workshops, formative assessments are usually more valuable + and easier to implement in practice. + They help you maximise the value of the workshop for learners while they are there. + - They also help with *metacognition* - + the awareness a learner has that they are succeeding in learning something new. +- Exercises are one important type of formative assessment +- Mental models and misconceptions + - 27+15=42 MCQ example from Instructor Training + - In addition to the prior knowledge we want learners to have they also have knowledge that can lead to misconceptions. + - It is important to detect misconceptions as early as possible + and formative assessments should help you do this +- Learners get feedback about what they have misunderstood - guided practice + +::::::::::::::::::::::::::::::::::::::: objectives + +- Explain what is meant by the intended and attained curriculum of a lesson. +- Describe the importance of regular assessment while a lesson is being taught. +- Design assessments to identify the misconceptions learners might have during your lesson. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- How can you measure learners' progress towards your lesson objectives? +- Why is it important to identify misconceptions as early as possible? +- Why should we create assessments before we have written the explanatory content of our lesson? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::: challenge + +## Exercise: misconceptions (5 minutes) + +What are the common misconceptions learners can have about the topic of your lesson? +How might you identify that misconception in your learners while they follow your lesson? +Share your answer in the collaborative notes document. + +Hint: Try thinking about related or common tools the learners might know and how +applying that prior knowledge might lead to a misconception with +the topic you are teaching. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::: challenge + +## Exercise: designing a diagnostic exercise (20 minutes) + +Create a multiple choice question (MCQ) that could be used in your lesson, +to detect the misconception you identified above. +As well as the correct answer, +include 1-3 answer options that are not obviously incorrect (*plausible distractors*) +and have *diagnostic power* +i.e. each incorrect answer helps you pinpoint the exact misconception carried by the learner. + +Share your MCQ in the collaborative notes document. + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::: challenge + +## Exercise: reviewing formative assessments (10 minutes) + +**(this exercise will only work if participants have sufficient knowledge of their partner's topic)** + +The Trainers will group you into pairs. + +Review the MCQ designed by your partner. When providing feedback, try to answer the following questions: + +- Is the question clear and easy to understand? Could the wording be improved in some way? +- Are the incorrect answers to the MCQ plausible distractors? +- Do the incorrect answers provide diagnostic power, to help an Instructor identify the misconception the learner has? +- Are there any incorrect answers missing i.e. are there other misconceptions that could be detected with this MCQ? + +Share your feedback in the collaborative notes document. + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- First key point. Brief Answer to questions. (FIXME) + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + diff --git a/10-wrap-up1.md b/10-wrap-up1.md new file mode 100644 index 000000000..36ac4dfcb --- /dev/null +++ b/10-wrap-up1.md @@ -0,0 +1,29 @@ +--- +title: Wrap-up +teaching: 15 +exercises: 0 +--- + +Something to wrap up the first day of the workshop. + +::::::::::::::::::::::::::::::::::::::: objectives + +- FIXME + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- FIXME? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- First key point. Brief Answer to questions. (FIXME) + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + diff --git a/11-exercises.md b/11-exercises.md new file mode 100644 index 000000000..dc3f81bbc --- /dev/null +++ b/11-exercises.md @@ -0,0 +1,259 @@ +--- +title: Designing assessments +teaching: 25 +exercises: 70 +start: yes +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- Choose the format for an exercise based on the outcome it is intended to measure. +- Display exercises and their solutions in a lesson site. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- Why are exercises so important in a lesson? +- What are some different types of exercises, and when should they be used? +- How should exercises be presented in a lesson website? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + +## Exercise Your Memory + +A simple model of memory is that individuals have two types of memory, +working (also called short-term) and long-term. +Long-term memory is essentially unlimited storage but slow to access whereas +working memory is quicker to access but can only hold a limited number of items at a time. +For instructors, the goal is to help learners move the new things they've learned from +working memory into long-term memory. +One of the ways lesson developers can aid in this process is through exercises. +In addition to providing formative assessments for instructors, exercises help move +new skills and concepts into long-term memory by providing learners an opportunity +to practice what was recently learned. +Exercises should occur frequently throughout the lesson because they move items +to long-term memory and free up learners' working memory for new items. + + +Creating exercises builds upon the learning objectives you created earlier in the lesson design process. +You can design exercises based on the actions/skills you described in your +learning objectives (the learning outcomes you intend for the lesson). +This will be easier if your wrote learning objectives with specific action verbs. +Specific verbs can help you decide what action you want the learners to perform in the exercise. +E.g. actions such as "explain" and "describe" may be better assessed by discussions +and multiple choice questions, while "solve," "construct," "test" and other +higher-level cognitive skills may be better assessed by debugging tasks, [code-and-run][code-and-run], +or use-in-a-different-context exercises. + +::: callout + +### Resources to Explore for More Example Assessment Types + + - [Exercise Types Chapter from Teaching Tech Together](https://teachtogether.tech/en/index.html#s:exercises) + - [Edutopia's 56 Examples of Formative Assessment](https://www.edutopia.org/groups/assessment/250941) + - [H5P Examples and Downloads for Interactive Content](https://h5p.org/content-types-and-applications) + +::: + + + +:::::::::::::::::::::::::::::::::::::: challenge + +## Exercise: Exercise Types and When to Use Them (15 minutes) + +The Trainers will assign you to pairs or small groups, +and give each group an exercise type to focus on. +Each group should assign a notetaker, +to summarise your discussion at the end of the exercise. + +Read about your given exercise type +[in the *Exercise Types* chapter of *Teaching Tech Together*](https://teachtogether.tech/en/index.html#s:exercises) by following the relevant link below. + +- [fill-in-the-blanks][blanks] +- [Parsons problems][parsons] +- [minimal fix][minimal] + +Then, discuss the following questions together: + +- What kind of skills would an exercise of this type assess? + Try to identify some action verbs like those we used to write lesson objectives earlier in the workshop. +- Would this type of exercise be suited to a novice audience? + Or is it a better fit for intermediate or advanced learners? +- Would this kind of exercise work well in an in-person workshop setting? + Would it be better suited to self-directed learning and/or a virtual workshop? + +Share the major points of your discussion in the collaborative notes document. + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + +As you discussed with your group in the last exercise, +different types of learning objectives work better for novices, +while others are a better fit for competent practitioners or experts. + +This can be understood in terms of the types of exercises that suit the objective: +exercise types that help manage cognitive load for the learner, +such as [faded examples][faded-ex] and [Parsons problems][parsons] +(which both provide a lot of the process/code and allow the learner to focus on a specific concept or skill) +are a good fit for a novice, to whom all elements of the topic are new. +However, these kinds of exercise do not provide an opportunity for learners +to develop higher-level skills, +such as the ability to create whole new functions or scripts, +or to extrapolate from the examples they have seen to solve a different kind of problem. +Indeed, example and exercise types that are helpful to novices +[may even be counter-productive for learners with a greater level of expertise][kirschner-2006]. + +Thus you want to choose your objectives to fit your intended audience and your exercise formats to fit your objectives. + + +:::::::::::::::::::::::::::::::::::: testimonial + +*"Different types of LOs are better fit for novices, +while others are better fit for competent practitioners, etc and +if exercises (formative assessments) are well aligned to LOs, +[they] will automatically serve the corresponding audience. +Thinking in terms of LOs +(What should a learner do in order to achieve this specific LO? +Is this LO exactly what learners are expected to achieve by the end of this piece of instruction? etc.) +is easier than thinking in terms of LOs + audience + content. +LOs should be tailored to the audience, and, +if this is well done, you may stop worrying about the audience. +Create LOs for the specific audience and create assessments for specific LOs."* + +\- Dr. Allegra Via, Carpentries Instructor Trainer + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + +:::::::::::::::::::::::::::::::::::::: challenge + +## Exercise: Assessing an Objective (30 minutes) + +Using one of the exercise formats you have learned about so far, +design an exercise that will require learners to perform one of the actions +described in the objectives you wrote for your lesson, +and that assesses their ability to do so. + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +## Demo of Writing an Exercise + +Well-designed exercises are one of the most valuable resources for an instructor and +any time spent on this is well invested. + + +To create an exercise in The Carpentries Workbench, +you can use colon-delimited sections called 'fenced divs'. +In fact [there are many types of boxes in the lesson infrastucture that use fenced divs](https://carpentries.github.io/sandpaper-docs/instructor/component-guide.html#callout-blocks). +In the Workbench, exercises are divided into two categories: _discussions_ (where the main task is for participants to discuss a topic or prompt) and _challenges_ (where the main task is a problem to be solved). + +To start a challenge fenced div the line must contain at least 3 colons, then the `challenge` tag. +Then the content of the challenge is included on the following lines. +Finally, you can close the fenced div using another line with least 3 colons. + +```markdown +:::::::::::::::::::::::::::::::::::::: challenge + +### Challenge Title + +Challenge text, code, and other information goes here + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +``` + +If you also want to include an expandable solution box for the challenge you can +add a solution fenced div within the challenge box. +The format is the same as for a challenge except the tag is `solution` instead. +Note the solutions can all be expanded for more accessible reading using the "Expand All Solutions" +option at the top of each episode. + + +``` +:::::::::::::::::::::::::::::::::::::: challenge + +### Challenge Title + +Challenge text, code, and other information goes here + +:::::::::::::: solution + +### Solution Title + +Solution text, code, and other information + +::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +``` + +For readability, you may want to have the length of the closing lines match the opening lines. +See in the above how the challenge and the nested solution's closing lines are similar lengths to the their corresponding opening lines. +For more information about creating exercises see the [Workbench Documentation for Exercises](https://carpentries.github.io/sandpaper-docs/episodes.html#exerciseschallenges). + +:::::::::::::::::::::::::::::::::::::: challenge + +## Exercise: Formatting Exercises in a Lesson Site (15 minutes) + +Using the approach demonstrated above, +format the MCQ you designed previously as an exercise in your lesson site. + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +Some other types of formative assessment include: + +- **Think, pair, share** - Learners _think_ about an answer to a question, _pair_ up +with a classmate to discuss their answer, and then _share_ out the consensus they came to +with the class. +- **Sticky notes and written feedback** - Learners each get two colors of sticky notes. +If they fall behind or run into an issue, they can put up the +color that signals they need help. +If they have completed and exercise or think the instructor could speed up, they put their +other sticky note up. +Then at breaks these stickies can turn into written feedback "minute cards", where the learner +writes down one thing they were confused about or that could be improved and one thing that went well +or they really liked learning. +- **Reflective assessment** - Learners spend time reflecting on what they have learned so far. +Reflection aids in transferring newly learned concepts into long-term memory and can be really helpful for "metacognition", where learners think about the process of learning, becoming aware of their progress towards acquiring new skills. +Developing metacognition improves learners' ability to guide their own learning on a topic after they have finished the lesson. +Reflection exercises can include using what was taught to label a diagram, draw a concept map, free write, or fill in a guided worksheet. + + + +:::::::::::::::::::::::::::::::::::::: challenge + +## Exercise: More Practice with Fenced Divs (10 minutes) + +Return to the bulleted list of lesson objectives you added to the `index.md` file of your lesson and +use fenced divs to display it in a formatted box with the `.prereq` class. +Note that all lesson objectives in fenced divs will be combined into +one box at the top of each episode. + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + + +[blanks]: https://teachtogether.tech/en/index.html#fill-in-the-blanks +[code-and-run]: http://teachtogether.tech/en/index.html#code-run +[faded-ex]: https://teachtogether.tech/en/index.html#faded-examples +[parsons]: https://teachtogether.tech/en/index.html#parsons-problem +[minimal]: https://teachtogether.tech/en/index.html#minimal-fix + + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- Exercises are important for learners to move what they've learned to long-term memory. +- Some types of exercises are better for particular audiences and to address certain objectives. +- Exercises (and solutions) go in blocks using fenced divs in the lesson. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + diff --git a/12-short-break.md b/12-short-break.md new file mode 100644 index 000000000..64981b494 --- /dev/null +++ b/12-short-break.md @@ -0,0 +1,12 @@ +--- +title: Break +teaching: 0 +exercises: 0 +break: 15 +--- + +Take a break. If you can, move around and look at something away from your screen to give your eyes a rest. + + + + diff --git a/13-narrative.md b/13-narrative.md new file mode 100644 index 000000000..9cdd29641 --- /dev/null +++ b/13-narrative.md @@ -0,0 +1,176 @@ +--- +title: Example data and narrative +teaching: 15 +exercises: 50 +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- Find candidate datasets to use in a lesson. +- Evaluate the suitability of a dataset to be used in a lesson. +- Choose examples that will prepare learners for formative assessments in the lesson. +- Develop a story + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- Why should a lesson tell a story? +- What considerations are there when choosing an example dataset for a lesson? +- Where can I find openly-licensed, published data to use in a lesson? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +## Creating a narrative + + + +Writing your lesson as a story helps learners stay motivated and engaged. +The story you create can also help learners more easily connect how the skills they +are learning now could be useful after the workshop. +You can enable learners to make connections between what they learn in your lesson and their +own work by creating a narrative that resembles a situation the learners might +encounter there. +Depending on the tool you are teaching, you might also include a particular dataset as a part of the story you are weaving into your lesson. +It is common for lessons to include a dataset that is used in examples and discussed throughout. +This can help you maintain a narrative flow and make the lesson feel more authentic +Even if your topic doesn't require a dataset, deciding on a consistent narrative will +help create a flow between lessons and reduce cognitive load for learners. + + +## Finding a dataset + +When searching for a dataset to use in your lesson, +there are a number of factors to consider. +First, if possible you want the dataset to be an authentic use +case for researchers in your target audience. +This means balancing the size and complexity of a dataset +while avoiding additional cognative load for learners. +The dataset may need a certain number of observations +to demonstrate some of the skills you are teaching or have a +number of variables that is sufficiently similar to what learners may encounter +in their work to feel authentic. +At the same time, you want your learners to be able to interpret the +data fairly easily during the lesson so they can focus on the skills +you are teaching. +This may mean you will need to subset your dataset or remove variables +observed. +You may want to also include and review a data dictionary in your lesson, +explicitly taking the time to review the information included in the +dataset. +For inspiration, see the [Social Sciences Data Carpentry data dictionary](https://datacarpentry.org/socialsci-workshop/data/). +An additional factor to consider when choosing a dataset to include is +the license. +You want to find a dataset where the data provider allows for you to freely use it. +The best option is a dataset with a CC0 (Public Domain Dedication) license, as +other licenses may have more ambiguity around data reuse. +Lessons included in [The Carpentries Incubator][carpentries-incubator] are encouraged to use CC0 licensed data, and may be required to do so to qualify for peer review in [The Carpentries Lab][carpentries-lab]. +Even with a CC0 license, you will still want to follow best practice in +giving attribution to the data provider or collecting agency. + +:::::::::::::::: callout + +## More CC0 License Reading + +If you'd like to read more about CC0 and CC-BY, Katie Fortney wrote an excellent +[blogpost on why CC-BY is not always a good fit](https://osc.universityofcalifornia.edu/2016/09/cc-by-and-data-not-always-a-good-fit/). + +:::::::::::::::::: + + +An example dataset used in the Data Carpentry Ecology lessons is the [Portal +Project Teaching Database](https://figshare.com/articles/dataset/Portal_Project_Teaching_Database/1314459). This dataset is an actual ecological research project that was simplified for teaching. +The reuse of this dataset throughout the Data Carpentry Ecology lessons helps +stitch together the process of data analysis on throughout the workshop, from +data entry and cleaning to analysis and visualization. + +When deciding on a dataset, it is also important to consider the ethical use of +each dataset considered. *Does the data contain personally identifiable information?* +*Was the data collected without permission from the groups or individuals included?* +*Will the data be upsetting to learners in the workshop?* +If the answer to any of these questions might be yes, you will need to do more +research on it and continue to look for other options. Commonly data is misused +from historically excluded and exploited groups. +The [CARE Principles for Indigenous Data Governance](http://doi.org/10.5334/dsj-2020-043) (Collective Benefit, Authority to Control, Responsibility, and Ethics) are good starting point +for thinking about data sovereignty and considering the ethics of data collected +about individual or groups of people. + + +### Examples of Public Repositories + +When looking for data to reuse, consider public repositories in the subject area +for your lesson or general data repositories such as: + - [Dryad](https://datadryad.org/) + - [The Data Cuartion Network's datasets](https://datacurationnetwork.org/datasets/) + - [The Offical Portal for European Data](https://data.europa.eu/) + - [DataONE](https://www.dataone.org/) +- [The Official Portal for Argentina Data](https://www.datos.gob.ar/) - (In Spanish) + +:::::::::::::::::::::::::::::::::::::: challenge + +## Exercise: Choosing a Dataset or Narrative (30 minutes) + +Referring to the advice given above, find an appropriate dataset or a narrative for your lesson. +Identify one or more potential candidates and note down the advantages and disadvantages of each one. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +Learners are motivated if you **teach most useful first**. +As you think about what story your lesson will tell, it is important to put +the pieces that are most interesting to learners up front. +If they are able to quickly learn tools or skills that they see as useful from your +lesson, they will be more interested in continuing to learn other concepts that are +needed. +You may notice this trend in many of the Software Carpentry lessons. In particular, +many of the coding language lessons (R and python) have the learners create a plot +very early in the lesson and then go back and teach coding fundamentals such as loops +and conditionals. Visualization of data is often a very motivating and much needed +skill by learners. Getting to visualization early, keeps learners interested in +learning the additional and vital skills where the application might be less clear. + +:::::::::::::::::::::::::::::::::::: testimonial + +[*"Let them eat cake (first)."*](https://www.youtube.com/watch?v=fQ4t7p6ZXDg) + +\- Dr. Mine Çetinkaya-Rundel + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + +:::::::::::::::::::::::::::::::::::::: challenge + +## Exercise: Examples Before Exercises (20 minutes) + +Looking back at one of the exercises you designed before: +what examples could you include in your narrative to teach learners the skills +they will need to apply to complete the formative assessments you have designed? + +Outline one of these examples in your episode file. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + + +## Summary + +Remember, even if you do not need a dataset for your lesson, you should +decide on a narrative. +Centering your lesson around a central example reduces the cognitive load of +switching between examples throughout the lesson. +Using an authentic, yet simple, dataset will also help reduce cognitive +load and help learners to see how they might apply what they learned to their own +projects. +It is also important to consider licensing and ethical considerations when looking +for a lesson dataset. + + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- Using a narrative throughout a lesson helps reduce learner cognitive load +- Choosing a lesson includes considering data license and ethical considerations. +- Openly-licensed datasets can be found in subject area repositories or general data repositories. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + diff --git a/14-long-break.md b/14-long-break.md new file mode 100644 index 000000000..8105d393d --- /dev/null +++ b/14-long-break.md @@ -0,0 +1,12 @@ +--- +title: Break +teaching: 0 +exercises: 0 +break: 60 +--- + +Take a break. If you can, move around and look at something away from your screen to give your eyes a rest. + + + + diff --git a/15-explanation.md b/15-explanation.md new file mode 100644 index 000000000..144eb39bc --- /dev/null +++ b/15-explanation.md @@ -0,0 +1,172 @@ +--- +title: How to write a lesson +teaching: 30 +exercises: 40 +--- + +- Explanatory text is the connective tissue between your examples and exercises + (I read this way of describing it somewhere - need to find the reference...). + The goal is to ensure coherent flow from one exercise to another. +- How much is too much? I.e. how verbose should your explanatory content be? + - A question of personal style, and preference for in-person vs self-directed learning (see below) + - but the aim is to provide all the relevant information + with a minimum of additional content that is not directly required + (extraneous cognitive load and wasted time) + to help learners reach the objectives you have set out. +- In many Carpentries lessons, callout boxes are used for asides and short tangents + e.g. points that might be relevant to some audiences but are not essential to the flow of the lesson. + (As such, they should be kept to a minimum.) + +::::::::::::::::::::::::::::::::::::::: objectives + +- Estimate the time required to teach a lesson. +- Summarise the content of a lesson as a set of questions and key points. +- Connect the examples and exercises in a lesson with its learning objectives. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- Why do we write explanatory content last? +- How can I avoid demotivating learners? +- How can I prioritise what to keep and what to cut when a lesson is too long? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: callout + +## Lesson pages for the instructor and the learner + +TODO brief discussion of trade-offs between preparing a lesson site for +use as an instructional guide vs use as a self-directed learning resource. +(notes below) + +Self-directed learning resources tend to be more verbose, +where instructional guides can be aimed at an audience more able to "read between the lines." +Very sparse text is less likely to be re-usable by other Instructors. +In general, it is not a good idea to assume others (learners or instructors) +will know what you were thinking when you wrote the content +so, if in doubt, be explicit. + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::: discussion + +## Discussion (10 minutes) + +At what point is a lesson too long? +How might you prioritise what to keep if you have to cut it down? + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +- Reminder: trying to fit too much content into a lesson is counter-productive. + It is better to cover less and teach people less, + than to cover more and teach people even less +- Also worth considering the (realistic) maximum viable length of a workshop + that would teach your lesson + e.g. it is unusual to be able to convince people to attend a workshop that lasts four full days. + (and better to teach people two days-worth of material than teach no-one four days-worth.) + Carpentries workshops have settled on two days, + but many in our community run three-day workshops to cover additional material. +- What is it essential that you include? + What can you leave out if you have to? + - Are there intermediate checkpoints that you can write in, + so that the workshop is not reliant on getting through the whole lesson to + "bring everything together?" +- In the end, the only way to know for sure is to pilot the lesson, + measuring how long it takes to teach. (link to pilot notes template) + But, as a general rule, + it is better to assume that you are under-estimating + rather than over-estimating the length. + Experience suggests that that is most likely correct, + and anyway it is better to have spare time for discussion, + revisiting exercises, etc + than to try to rush through the remaining material in limited time. + - If, after teaching your new lesson, you find that you did not have time to cover all the content, + approach cutting down the lesson by identifying which learning objectives to remove. + Then take out the objective(s) and the corresponding assessment(s) and explanatory content. +- Consider adding suggestions for objectives that can be skipped to the Instructor Notes for the lesson. +- Managing cognitive load + +:::::::::::::::::::::::::::::::::::: testimonial + +*"the five ways to handle an extraneous overload situation are to:* + +- *eliminate extraneous material (coherence principle),* +- *insert signals emphasizing the essential material (signaling principle),* +- *eliminate redundant printed text (redundancy principle),* +- *place printed text next to corresponding parts of graphics (spatial contiguity principle), and* +- *eliminate the need to hold essential material in working memory for long periods of time (temporal contiguity principle)."* + +\- [Renkl (2014)](https://www.cambridge.org/core/books/cambridge-handbook-of-multimedia-learning/worked-examples-principle-in-multimedia-learning/8753055D1FB47CF1E2BB897FD44FBEF8) + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +- How can you avoid demotivating your learners? + - Dismissive language, stereotypes (check your learner profiles too!) + - Expert awareness gap + - Think back to 27+15=42 MCQ example and + how challenging it can be to remember the common mistakes in something you mastered a long time ago +- Fluid representations, unexplained or unnecessary jargon, unexplained assumptions, sudden jumps in difficulty/complexity +- Accessibility + - Avoid regional/cultural references and idioms that will not translate across borders/cultures + - Contractions + - Alternative text for figures/images (including for data visualisations [https://medium.com/nightingale/writing-alt-text-for-data-visualization-2a218ef43f81](https://medium.com/nightingale/writing-alt-text-for-data-visualization-2a218ef43f81)) - [the Workbench documentation describes how to add alt-text and captions to images in a lesson](https://carpentries.github.io/sandpaper-docs/episodes.html#figures) + - Header hierarchy (no h1 headers in the lesson body, no skipped levels e.g. h2 -> h4) + - Use descriptive link text - no "click here" or "this page" etc + - Image contrast \& tools to check this + +:::::::::::::::::::::::::::::::::::::: challenge + +## Exercise: Alternative text for images (5 minutes) + +TODO/exclude to free up some time + +multiple choice question with an example image and a few different options for alt text. +Ask trainees to choose the most appropriate option. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +- Defining key terms and Glosario +- Questions and key points + - what and who are these for? how do they tend to be used? + +:::::::::::::::::::::::::::::::::::::: challenge + +## Exercise: Completing episode metadata (5 minutes) + +Add key points and questions to your episode. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::::: challenge + +## Reflection Exercise (20 minutes) + +TODO based on +"Map out the relationships between the LOs, +the LEs via which they will be delivered \& those specific items of content +(e.g., item A sup- ports LO 1, \& will be delivered using a lecture). + +- Is there any piece of content that doesn't support any LO(s)? +- Is there at least one piece of content for each LO? +- Is there at least one LE for each piece of content?" + +What do you still need to add/work on? What can you remove/consider removing? +What diagram or other visual aid could you add to supplement your text? + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- First key point. Brief Answer to questions. (FIXME) + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + diff --git a/16-short-break.md b/16-short-break.md new file mode 100644 index 000000000..64981b494 --- /dev/null +++ b/16-short-break.md @@ -0,0 +1,12 @@ +--- +title: Break +teaching: 0 +exercises: 0 +break: 15 +--- + +Take a break. If you can, move around and look at something away from your screen to give your eyes a rest. + + + + diff --git a/17-operations.md b/17-operations.md new file mode 100644 index 000000000..0f322fd27 --- /dev/null +++ b/17-operations.md @@ -0,0 +1,57 @@ +--- +title: How we operate +teaching: 25 +exercises: 5 +--- + +- The Incubator/Lab/Lesson Program ecosystem + - How all these things fit together +- The lesson life cycle + - Stages: pre-alpha, alpha, beta, stable + - Pilot workshops + - Why these are important + - (Briefly) the practicalities of organising/teaching them, collecting feedback, etc + - Lesson publication and review +- Connecting with The Carpentries curriculum community + - the lesson-dev Slack channel + - creating your own Slack channel for your lesson + - the incubator-developers TopicBox list + - co-working sessions + - further resources for lesson developers + +::::::::::::::::::::::::::::::::::::::: objectives + +- Describe the life cycle of a lesson. +- Summarise the path a new lesson can take through The Carpentries Incubator and Lab. +- Connect with other members of the community. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- What does The Carpentries lesson development ecosystem look like? +- What are the important milestones in the development of a new lesson? +- How can The Carpentries lesson development community help me complete my lesson? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::: challenge + +## Exercise: join relevant channels (5 minutes) + +TODO: time for participants to find and join relevant communication channels + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- First key point. Brief Answer to questions. (FIXME) +- Teaching a lesson for the first time is an essential intermediate step in the lesson development process. +- First key point. Brief Answer to questions. (FIXME) + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + diff --git a/18-preparing.md b/18-preparing.md new file mode 100644 index 000000000..0c5566ed0 --- /dev/null +++ b/18-preparing.md @@ -0,0 +1,121 @@ +--- +title: Preparing to teach +teaching: 15 +exercises: 30 +--- + +By now you should have developed +objectives, +exercises/formative assessments, +and examples +for at least one of the episodes in your lesson. + +::::::::::::::::::::::::::::::::::::::: objectives + +- Summarise lesson content as a teaching plan. +- Add setup instructions and Instructor Notes to the lesson site. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- What can I do to prepare to teach my lesson for the first time? +- What information should be recorded for instructors teaching a lesson? +- How should I communicate lesson setup instructions to learners? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::: challenge + +## Exercise: Prepare a teaching plan (15 minutes) + +Create a bullet point list or brief notes describing +what you will say and do when teaching the episode you have been focussing on +during this training. + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::: testimonial + +*"I usually create detailed notes organised in a concept map/workflow in order to make everything consistent. +I also write next to each bit of teaching the time approximately needed. +For each lesson I create (and reuse when I teach again the same lesson) +very detailed notes of what happens during the lesson, +including teaching goals and LO(s) I mean to achieve with each bit of lesson. +This rich lesson plan requires a lot of work the first time I teach a lesson, +but reduces a lot the preparation time of future lessons and are super useful to other teachers."* + +\- Dr. Allegra Via, Carpentries Instructor and Instructor Trainer + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +- Using figures and visual aids + - Remember the alt text + - Call back to placing explanatory text adjacent to relevant part of visualisation +- Working with the lesson infrastructure: + - Setup instructions + - This is time well-invested. Clear instructions now may give you more time when teaching the lesson. + - Discuss briefly what belongs in Instructor Notes pages: + - strengths and weaknesses of current design + - what has been tried before and what worked/did not work + - tips for teaching the lesson/particular sections + - challenges encountered + - parts that seem to cause biggest trouble/most confusion for learners (i.e. where to tread carefully), etc + +::::::::::::::::::::::::::::::::::::: discussion + +## What questions do you have? (15 minutes) + +The homework from this workshop includes a trial run of one of the episodes +you have been developing in your lesson, to a real audience. + +Thinking about this task, what questions do you have about how you should +approach teaching that trial run? +Is there anything you are unsure of? +What resources might help you prepare for that experience? + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::: challenge + +## Exercise: homework + +The final part of this training will focus on the skills needed to collaborate +effectively. Before that there will be a break, +during which we would like you to complete the following three tasks: + +1. Teach one episode of your lesson (probably the one you have been working on in these two days) + See the [Lesson Trial Runs](../learners/trial-runs.md) page for full details. +2. After your trial run has concluded + (immediately after, or when you have reviewed any feedback you collected from learners), + note down your answers to the following questions: + - What worked? + - What did not? + - What will you do differently next time? + - What will you change in your material you taught? + We will refer to these notes when we reconvene for the last section of this training. +3. Based on your experience teaching the material and the feedback you received from your learners and helpers, + make a list of issues you have identified with the material you prepared, e.g. + - examples that did not work as expected, + - improvements that could be made to exercises, + - parts that learners found particularly challenging, + - unexpected questions or misconceptions that came up during the trial run, + - etc. + We will return to these notes during the final training session, + so please make sure you save them somewhere you will be able to find them again easily when the time comes. + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- First key point. Brief Answer to questions. (FIXME) + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + diff --git a/19-wrap-up2.md b/19-wrap-up2.md new file mode 100644 index 000000000..93d65656c --- /dev/null +++ b/19-wrap-up2.md @@ -0,0 +1,29 @@ +--- +title: Wrap-up +teaching: 30 +exercises: 0 +--- + +Something to wrap up the second day of the workshop. + +::::::::::::::::::::::::::::::::::::::: objectives + +- FIXME + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- FIXME? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- First key point. Brief Answer to questions. (FIXME) + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + diff --git a/20-reflecting.md b/20-reflecting.md new file mode 100644 index 000000000..02740d130 --- /dev/null +++ b/20-reflecting.md @@ -0,0 +1,87 @@ +--- +title: Reflecting on trial runs +teaching: 10 +exercises: 45 +start: yes +--- + +Welcome back! +In this section of the training, +we will learn more about the skills and tools you can use to become +an effective collaborator on an open source lesson. +Before moving on to cover that, +we will spend some time reflecting on and discussing the experience of +teaching new lesson material for the first time. + +::::::::::::::::::::::::::::::::::::::: objectives + +- Reflect on the experience of teaching part of a lesson for the first time. +- Identify changes and improvements that can be made as a result of trialling lesson material. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- What did I learn when I taught my lesson? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::: challenge + +## Exercise: Check in (10 minutes) + +Re-introduce yourself and remind the group about the lesson you have been working on. + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +In the break since last time, +you should have trialled some of the lesson you set out to develop in +this training. Congratulations on organising and delivering your first pilot! +We will use this session to reflect on that experience, +and take some steps to ensure that the feedback and notes you gathered during +the trial run are used to improve the quality of your lesson. + +::::::::::::::::::::::::::::::::::::: discussion + +## Discussion: trial runs (35 minutes) + +Look back at the notes you took and feedback you received during your trial run (5 mins). + +Now report out to the other participants about that trial run. +Try to answer some or all of the following questions: + +- What worked well both in terms of content and delivery? +- What did not work as well? +- How close were your time estimates to the actual time needed to teach the material and finish exercises? +- How did the audience perceive the difficulty level of the material? +- What will you do differently next time? +- What will you change in the material you taught? +- What will you change in the way you collect feedback in future pilots? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +Moving forward from your first pilot, the next steps to consider are: + +- Recording all the identified changes and improvements that can be made to the lesson material and assigning a person from the team responsible for each task. The above exercise provided some reflection points after a trial run; in terms of lesson content they may translate into the following considerations: + - is the material too dense, does it need extra explanations? + - would adding a diagram help explain or curate things better? + - is there too much content for one episode and do you need to split into smaller teaching units? + - do you need to re-organise and move some content around to improve the flow and narrative? + - are there enough exercises and practical work? + - do you need to realign your lesson objectives and key messages? +- Deciding if some of the feedback you will not action. Remember, you do not need to respond to every piece of feedback you receive. For example, it is easy to fall down the rabbit hole of adding extra material just because someone suggested it may be a useful thing - sometimes adding a link to extra reading is sufficient. You need to be able to draw a line under any extra modification suggestions to keep you in scope and on schedule. +- Schedule follow-up co-working sessions with your team to carry on working on fixing issues and adding new content to maintain the momentum. +- Think about the timeline for your next pilot(s), even provisionally, to help you set milestones and targets to work towards. +- Consider writing up your pilot experience in a mini blog post that you can share with the community. + +Designing and developing quality lessons is hard - there are many pieces of a puzzle that have to come into place: both pedagogical and organisational. Do not be disheartened with the amount and type of feedback you may have received. Even Carpentries lessons that have been around for 10+ years receive improvement suggestions and fixes almost on a daily basis. From our experience, bigger lessons that are delivered over a few days require several full pilots before they can even be considered for a [beta](https://carpentries.github.io/curriculum-development/the-lesson-life-cycle.html) release. Planning smaller lesson trials (where you test only a portion of a lesson) and doing them more often with a friendly audience from your local groups and close colleagues is more manageable and will help you make steady progress. + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- ["Perfect is the enemy of good"](https://en.wikipedia.org/wiki/Perfect_is_the_enemy_of_good) - your lesson does not need to be perfect before you pilot or release it for community review. Getting early feedback from target audience will help you avoid straying off your lesson plan. +- Identify changes and improvements that you want to make as a result of trialling your lesson and schedule co-working sessions to work on these tasks. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + diff --git a/21-short-break.md b/21-short-break.md new file mode 100644 index 000000000..64981b494 --- /dev/null +++ b/21-short-break.md @@ -0,0 +1,12 @@ +--- +title: Break +teaching: 0 +exercises: 0 +break: 15 +--- + +Take a break. If you can, move around and look at something away from your screen to give your eyes a rest. + + + + diff --git a/22-external.md b/22-external.md new file mode 100644 index 000000000..baa9b59e5 --- /dev/null +++ b/22-external.md @@ -0,0 +1,153 @@ +--- +title: Collaborating with newcomers +teaching: 30 +exercises: 25 +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- Adjust a lesson repository to attract potential collaborators. +- Create and modify issue and pull request templates in GitHub. +- Identify strategies to encourage regular development and maintenance of a lesson. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- What makes a project welcoming for newcomers? +- What information should I provide about the project to potential collaborators? +- How can I ensure regular progress on lesson development? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +So far, the focus of the training was on lesson development skills. In this section, we will learn more about the skills and tools you can use to become an effective collaborator on an open source lesson development project and how to employ your lesson development skills in a team environment. Collaboration skills covered here are transferrable to any similar open source project you may be involved with. + +You may start working on projects by yourself or with a small group of collaborators you already know, but open source projects in the Carpentries community often grow beyond that small group. Community collaboration is the cornerstone of The Carpentries - all curricula and various programmes are developed together by the community members across borders, domains and backgrounds. Most initiatives are done through community consultation and collaboration is used as a pathway to empower people, give members a sense of purpose in the community and realise shared goals. + +Collaboration helps bring different perspectives to solving a problem and share the load of the required work to develop, pilot, and, later on, maintain the lesson. People drop in and out of projects for various reasons and their levels of involvement may vary over time due to other commitments - for this reason it is worth taking time from the outset to make a project welcoming for newcomers in order to achieve a steady number of people working on your project at any time. You should plan to make it easy for new collaborators to join, to set up a local workspace so that they can contribute, help them find tasks so that they know what to contribute, and make the contribution process clear so that they know how to contribute. You also want to make it easy to give people credit for their work on your project as well as for others to reuse and give credit to your project. From this episode on, we cover best practices for collaboration and tools available to us achieve it. + +## Documenting your lesson + +For collaborative projects, it is important to spend the time on ‘external-facing’ features, such as documentation, to make the project as welcoming and as easy to get involved in as possible for newcomers who may not have a deep grasp of the project or know all its existing problems. Such documentation will be useful to yourself and other team members at well, e.g. if you are trying to come back to the project after a break or are reusing it for a new collaboration in the future. + +Your lesson documentation should contain the following information, which should be kept up to date. + +### Description of the project - `README` file + +`README`, `README.txt` or `README.md` is a plain text or Markdown file located in the project's root directory representing the default landing or home page for repositories in GitHub (and similar project repositories) by convention. It represents the first piece of documentation that people will see when visiting your lesson repository, hence it should concisely explain what the lesson is about and who it is for, and contain links and pointers to further information. For example, `README` should include: + +- **lesson title** +- **lesson description** +- **rendered version of the lesson** - even though this is typically included in the `About` section of the repository, it is always useful to link to the URL where the rendered lesson is available +- **contact information** - include up-to-date email addresses or mailing lists or other details on how to get in touch with the lesson maintainers +- **contributing information** - this is an opportunity to list what kinds of contribution are sought and how to get involved in lesson development for new contributors. You can provide more details in a separate `CONTRIBUTING` file within the repository’s root directory and link to it from `README` +- **credits/acknowledgements** - make sure to credit those who have helped in the lesson's development or inspired it, and/or any resources/templates that you have reused. You can also link to a separate `AUTHORS.md` file within the repository’s root directory to list all the people who contributed to the lesson content (if this list starts to become too large to include in the `README` itself) +- **citation** - a convention is to include the citation information for your lesson in a separate `CITATION` file within the repository’s root directory (and link to it from `README`) so others can cite the use of the lesson in their own publications and media and it can also be automatically discovered by other applications. Citation can be a Digital Object Identifier (DOI) issued by a reputable DOI-issuing repository such as [Zenodo](https://zenodo.org/), which should be obtained as a permanent identifier as soon as your lesson reaches the beta stage, or an appropriate academic publication once your lesson becomes stable and is peer-reviewed. +Citation can be contained in a plain text file (`CITATION`, `CITATION.txt`), a Markdown file (`CITATION.md`), or in the recently adopted [Citation File Format](/~https://github.com/citation-file-format/citation-file-format) (`CITATION.cff`). The CFF is defined using [YAML](http://yaml.org/spec/1.2.2/) (which we already encountered in the `config.yaml` file for the lesson website) and is now [the recommended way of storing citations in GitHub](https://github.blog/2021-08-19-enhanced-support-citations-github/). Advantages of using CFF are that GitHub will automatically show the citation information in the sidebar, making it more visible and accessible for visitors to your repository. In addition, metadata from `CITATION.cff` files will automatically be used by [Zenodo](https://zenodo.org/) when registering the DOI for your lesson/project. CFF metadata is also recognised by the [Zotero reference manager](https://www.zotero.org/). +- **license** - a short description of and a link to the lesson’s license typically contained in a separate `LICENSE`, `LICENSE.txt` or `LICENSE.md` file within the repository’s root directory. The lesson repository created from the Carpentries lesson template already contains a default `LICENSE.md` file, but you should modify this to more accurately describe how the lesson content can be re-used by others. + +### Instructions for contributors - `CONTRIBUTING` file + +`CONTRIBUTING`, `CONTRIBUTING.txt` or `CONTRIBUTING.md` is a text or Markdown file within the repository's root directory where you should provide detailed description of the ways people can send their contributions, what kinds of contribution will be credited and in what ways. For example, at what point would someone be listed as an author and how you will credit contributions that are not recorded in the commit history of the project. The latter is particularly important for newcomers who may not be proficient with the use of GitHub's features for collaborative work, such as issues, mentions, pull requests and code review, but could still provide valuable input and contributions. + +Carpentries lesson repositories already have a generic Carpentries `CONTRIBUTING.md` file to get you started. You should review it and, if need be, modify it to fit your team's needs and way of working. For example, you may want to expand on what contributions you are *not* looking for if your lesson already contains more material than can be covered in a typical workshop. You can also detail all channels on which you are willing to receive contributions on if they are different from the defaults included in the file. + +### Issue and pull request templates + +Consider setting up issue and pull request templates to help newcomers who may not have much experience working on collaborative projects in GitHub. Such templates can provide a structure for the issue/pull request description, and/or prompt them to fill in answers to pre-set questions. Both can help contributors raise issues or submit pull requests in a way that is clear, helpful and provides enough information for maintainers to act upon (without going back and forth to extract it). GitHub provides a range of default templates, but you can also [write your own](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository). + +### Other documentation + +Once you have set up the basic documentation about your lesson, you may consider adding the following useful information to your documentation too: + +- set-up guides for installing and rendering the lesson locally. In most cases, a link to [The Carpentries Workbench documentation](https://carpentries.github.io/sandpaper-docs/) will be sufficient. +- how to create and modify the pages in the lesson + + +:::::::::::::::::::::::::::::::::::::: challenge +## Exercise: preparing your repository for collaboration (15 minutes) + +Spend some time doing **one of the following**: + +1. Modify the `README.md` and `CONTRIBUTING.md` files in your repository + to provide the relevant information for would-be contributors to your lesson: + - the name(s) of the current developer(s), linked to their GitHub profile(s) (README) + - contact information (README, CONTRIBUTING) + - guidance on how people should contribute, and what kinds of contribution you are most interested in receiving (CONTRIBUTING) + - links to any important background information (README) + - links to any funding bodies or host institutes that are supporting the development of the lesson (README) +2. Create a new issue or pull request template, or modfy an existing one, + to guide contributors on how best to begin collaborating with you on GitHub. + +Groups of collaborators taking this training together should discuss first how they will assign these tasks between them. +:::::::::::::::::::::::::::::::::::::::::::::::::: + +## Collaborating on a lesson + +### Boosting the visibility and attracting new collaborators + +In addition to having the complete documentation in the lesson repository, The Carpentries community provides a number of ways to further raise the visibility of the lesson among the broader community and encourage community members to contribute to its further development. For example: + + - listing issues from the lesson repository on [The Carpentries Help Wanted page](https://carpentries.org/help-wanted-issues/) + - featuring your lesson in [the Incubator Lesson Spotlight](https://docs.carpentries.org/topic_folders/lesson_development/spotlight.html) + - writing a blog post about the lesson for [The Carpentries Blog](https://carpentries.org/blog), and/or attending a community discussion call to promote the lesson + - advertising the lesson at various Carpentries mailing lists - e.g. [general discussion](https://carpentries.topicbox.com/groups/discuss), [instructors](https://carpentries.topicbox.com/groups/instructors), regional communities or specific curriculum lists + +You should also consider including your lesson in [Hacktoberfest](https://hacktoberfest.digitalocean.com/) and similar wider community open source events aimed at encouraging people to contribute to open source projects periodically throughout the year. + +### Issue labelling for newcomers + +You can encourage contributions to your lesson from newcomers by using specific labels on issues to highlight suitable opportunities to help. Apply the `good first issue` or `help wanted` labels to issues in your repository to indicate that the maintainers will particularly welcome help or pull requests fixing such issues. + +### Noticing when something happens + +GitHub implements a comprehensive [notifications system](https://docs.github.com/en/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications) to keep you up-to-date with activities in the lesson repository. GitHub also provides an additional useful notification feature for collaborative work - **Mentions**. The mention system notifies team members when somebody else references them in an issue, comment or pull request - you can use this to notify people when you want to check a detail with them, or let them know something has been fixed or changed (much easier than writing out all the same information again in an email!). You can use the mention system to link to individual GitHub accounts or whole teams for mentioning multiple people. Typing `@` in GitHub will bring up a list of all accounts and teams linked to the repository that can be "mentioned". + +Check out [GitHub's documentation on setting notifications on individual repository](https://docs.github.com/en/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository). You can choose whether to watch or unwatch an individual repository, or can choose to only be notified of certain event types such as issues, pull requests, mentions, etc. + + +### Making progress + +The following practices have been shown to help maintain steady progress with lesson development: + + - being responsive to notifications about activities and mentions + - scheduling regular co-working/sprinting sessions with team members +attaching your sprint sessions to other open source community activities, which may offer goodies, rewards and prizes for participants, can provide motivation and activity spikes + - working alongside other members of The Carpentries community at Maintainer or lesson development co-working sessions + - blocking time in your calendar for issue triage/solo material writing + - planning lesson pilots in advance to help set targets + + +Make sure to join the [Incubator lesson developers mailing list](https://carpentries.topicbox.com/groups/incubator-developers) to keep an eye on announcements and discussions relating to lesson development in the Carpentry community. + +:::::::::::::::::::::::::::::::::::::: challenge + +## Exercise: planning to collaborate (10 minutes) + +Use this time to plan how you will continue to make progress +with developing your lesson, and ensure that you are ready to respond to +external contributors when they arrive at your lesson. +This time is yours to do with as you think is best for yourself and your project, +but you might consider using it to do one or more of the following: + +1. schedule a lesson development co-working session with your collaborators, + and/or mark the next community co-working session in your calendar. +2. ensure that your the notification settings are appropriately configured for + your lesson repository. +3. contact The Carpentries team to ensure issues from your lesson will be + included on the Help Wanted page. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- *"If a project doesn’t make a good first impression, newcomers may wait a long time before giving it a second chance" - Karl Fogel, the author of ["Producing Open Source Software: How to Run a Successful Free Software Project"](https://www.oreilly.com/library/view/producing-open-source/0596007590/)*. +- You should make an active effort to attract potential collaborators and try to make them all feel welcome and included. [The Carpentries Help Wanted page](https://carpentries.org/help-wanted-issues/) and featuring in [the Incubator Lesson Spotlight](https://docs.carpentries.org/topic_folders/lesson_development/spotlight.html) can boost the visibility of your lesson. Creating the appropriate documentation and using GitHub features such as labels, and issue/pull request templates will help lower the barriers for contributions to your project. +- Scheduling regular co-working sessions, blocking time in the calendar for issue triage, and setting and being responsive to GitHub notifications will ensure regular progress on the lesson. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + + \ No newline at end of file diff --git a/23-long-break.md b/23-long-break.md new file mode 100644 index 000000000..8105d393d --- /dev/null +++ b/23-long-break.md @@ -0,0 +1,12 @@ +--- +title: Break +teaching: 0 +exercises: 0 +break: 60 +--- + +Take a break. If you can, move around and look at something away from your screen to give your eyes a rest. + + + + diff --git a/24-collaborating.md b/24-collaborating.md new file mode 100644 index 000000000..e2a940805 --- /dev/null +++ b/24-collaborating.md @@ -0,0 +1,125 @@ +--- +title: Collaborating with people you already know +teaching: 45 +exercises: 30 +--- + +::::::::::::::::::::::::::::::::::::::: objectives + +- Report and track issues with the GitHub interface. +- Review and provide feedback on contributions from collaborators. +- Prepare for a decision-making meeting between collaborators. + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- How can I use GitHub to manage a lesson development project? +- What communication channels are effective for a lesson development team? +- What strategies exist to help collaborators make decisions and govern an open source project? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + +In this episode we expand on how to use GitHub effectively among a group of known collaborators, building on top of tools and practices we introduced for working with newcomers. Everything you do to help your lesson be more attractive and informative to newcomers will benefit all collaborators. Here, we explore GitHub features to help you keep track of what needs doing on the lesson, making decisions and managing your project. + +## Managing issues + +**Issues** are GitHub's framework for managing issue/bug reports, feature requests, and lists of future work. They provide a single shared record of all the problems people have found with the lesson, and improvements that could be made, along with solutions and discussions around them. This helps the team to keep track of what they need to work on later, and reduces the chance of receiving redundant reports of issues you already know about. + +When you create an issue, you can add a range of details to it. An issue can be assigned to a specific team member - this can be a helpful way to know who is currently working to fix an issue or a way to assign responsibility to someone to deal with it. You can assign one or more labels to issues to classify or group them. Labels can also be given colours, allowing you to see at a glance from the Issues page the state of your project. The default labels available in GitHub include: + +- `bug` - indicates an unexpected problem or unintended behavior +- `documentation` - indicates a need for improvements or additions to documentation +- `duplicate` - indicates similar or already reported issues, pull requests, or discussions +- `enhancement` - indicates new feature requests, or if they are created by a lesson maintainer, indicate planned new features +- `good first issue` - indicates a good issue for first-time contributors +- `help wanted` - indicates that a maintainer wants help on an issue or pull request +- `invalid` - indicates that an issue, pull request, or discussion is no longer relevant +- `question` - indicates that an issue, pull request, or discussion needs more information +- `wontfix` - indicates that work won't continue on an issue, pull request, or discussion + +Check the [GitHub documentaiton on Issues](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/managing-labels) for the full reference. +We have already seen some of these labels - recall the `help wanted` and `good first issue` labels aimed at newcomers to your project discussed in the previous episode. You can also create your own custom labels to help with classifying issues. There are no rules really about naming the labels - use whatever makes sense for your project. Some conventional custom labels include: `status:in progress` (to indicate that someone started working on the issue), `status:blocked` (to indicate that the progress on addressing issue is blocked by another issue or activity), etc. + +:::::::::::::::::::::::::::::::::::::: challenge + +## Exercises: creating issues (15 minutes) + +After your trial run, +you should have created a list of issues you identified with your lesson. +Open issues on the GitHub repository for your lesson, +for each item on that list. +Remember to add labels to each issue according to its type, priority, etc. +As you create them, +you may also want to assign these issues to a member of your lesson development team. + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +## Managing communication + +Having an open, publicly-visible list of all the issues with your project is a helpful way of letting people know you are aware of issues and you are working on them. This can indicate to an external audience that the project is active. +It also provides you and your collaborators with an "at a glance" view of the state of the project, making it easier to prioritise future work. + +As we have seen in the previous episode, GitHub's notifications framework **Mentions** plays an important part in communicating between collaborators and is used as a way of alerting team members of activities and referencing one issue/comment/pull requests from another. + +[Slack](https://slack.com/) is commonly used in the Carpentries community for quick, day-to-day message exchange among teams. You can create your own [Slack workspace for free](https://slack.com/intl/en-gb/) or create a channel for your lesson development project under [the Carpentries public Slack workspace](https://swcarpentry.slack.com/). Note that the Carpentries Slack is an enterprise workspace so all messages and files will be retained and no messages will be lost (for free workspaces only the most recent 10,000 messages can be viewed and searched and file storage limit is 5 GB). + +Collaborators can also use other platforms to discuss lesson development or receive contributions from newcomers who are not yet fluent in using GitHub's systems of communication. The Carpentries can assist with creating a mailing list specific to the development of your lesson on their [TopicBox](https://carpentries.topicbox.com/) platform for managing threaded email discussions. Also make sure to join the [Incubator lesson developers mailing list](https://carpentries.topicbox.com/groups/incubator-developers) on TopicBox to keep an eye on announcements and discussions relating to lesson development in general within the Carpentries community. + +Meeting minutes are a useful way of providing a permanent record of the purpose of a meeting and what was talked about, including any decisions made or actions taken, that can be referred back to for any follow-ups. Recording meeting minutes does not have to be hard - remember that you are part of a team and there are many platforms that allow collaborative note taking. The Carpentries provides [CodiMD](https://codimd.carpentries.org/) and [Etherpad](https://pad.carpentries.org/) instances as two options for taking shared notes, widely used at workshops for sharing pieces of code, references and notes between instructors and learners. For some advice on holding effective meetings, see [the _Meetings, meetings, meetings_ section of Teaching Tech Together](http://teachtogether.tech/en/index.html#s:meetings) by Greg Wilson. + +## Project management + +Developing a lesson is a project and, like most projects, it consists of multiple tasks. Keeping track of the list of tasks the team has to do, progress on each, prioritising tasks for future development, sprints and releases, etc., quickly becomes a non-trivial task in itself. Without a good project management framework, it can be hard to keep track of what’s done, or what needs doing, and particularly difficult to convey that to others in the team or share the responsibilities. + +GitHub's project management framework **Project Board** is a tool for keeping track of all the different components of a project, and what their current status is. It does this using columns and cards - you break your project down into tasks which you write on cards, then move the cards between columns that describe the status of each task. Cards are usually small, descriptive and self-contained tasks that build on each other. Breaking a project down into clearly-defined tasks makes it a lot easier to manage and develop. GitHub project boards interact and integrate with the other features of the site such as issues and pull requests - cards can be added to track the progress of such tasks and automatically moved between columns based on their progress or status. + +GitHub provides template boards that by default contain the three ‘basic’ columns, with pretty self-explanatory names: + +- `To Do` +- `In Progress` +- `Done` + +If you add an issue or pull request to a card in the board, it will automatically be moved to ‘Done’ for you when you close the issue or merge the pull request. One common extra column is `On hold` or `Waiting`. If you have tasks that get held up by waiting on other people (e.g. to respond to your questions) then moving them to a separate column makes their current state clearer. + +You can also create a card without an issue. Such cards (or notes) can have detailed content like checklists. GitHub also allows you to convert a card to an issue so you can add labels or detailed comments to it. Sometimes, a card you thought was simple and self-contained might turn out to be a bigger task than you anticipated - in that case, it is sensible to create new cards that reference the one they broke off from. + +Once your project board has a large number of cards on it, you might want to begin priorisiting them. Not all tasks are going to be equally important, and some will require others to be completed before they can even be begun. Common methods of prioritisation include: + +- **Vertical position**: the vertical arrangement of cards in a column implicitly represents their importance. High-priority bugs go to the top of `To Do`, whilst tasks that depend on others go beneath them. This is the easiest one to implement, though you have to remember to correctly place cards when you add them. +- **Priority columns**: instead of a single `To Do` column, you can have two or more, for example - `To Do: Low Priority` and `To Do: High Priority`. When adding a card, you pick which is the appropriate column for it. You can even add a Triage column for newly-added issues that you’ve not yet had time to classify. This format works well for project boards devoted to bugs. +- **Labels**: if you convert each card into an issue, then you can label them with their priority - remember GitHub lets you create custom labels and set their colours. Label colours can provide a very visually clear indication of issue priority but require more administrative work on the project, as each card has to be an issue to be assigned a label. If you choose this route for issue prioritisation - be aware of accessibility issues for colour-blind people when picking colours. + +## Project governance + +In addition to managing your project on a day-to-day basis, you should consider a governance model for your lesson to describe the ground rules of participation, the roles that project participants can take on and the process for decision making within the project. You may wonder why you'd ever need a formal governance process - after all, everyone in your team is collegial, polite and hard-working. However, even among the most harmonious teams you will likely realise you need an agreed way to make decisions and resolve conflicts when your team encounters their first real disagreement. + +The moment your collaborator group exceeds 3 or 4 members (and fewer if the collaborators do not all know each other equally well at the outset) you should establish and document some kind of governance process. It will help mitigate any power imbalances which are expressed when one team member (or a group of team members) are more vocal and are able to dominate the decision-making process. It is advised to make these considerations early on, before your project grows too much and introducing structure and process into it becomes more difficult and complicated. Besides, if you do not establish these processes from the start, you are likely to discover the need to do so only when you first encounter disagreement within the team: a situation unlikely to provide perfect conditions for a discussion of governance. + +Here are some aspects of governing a project that you should consider. These are borrowed from [the _Working in teams_ chapter](https://merely-useful.tech/py-rse/teams.html) of [_Research Software Engineering with Python_](https://merely-useful.tech/py-rse/index.html), a book on how to work productively in small teams where everyone is welcome: + +- [Codes of Conduct](https://merely-useful.tech/py-rse/teams.html#teams-coc) +- [meeting rules](https://merely-useful.tech/py-rse/teams.html#teams-meetings) +- [decision-making process](https://merely-useful.tech/py-rse/teams.html#teams-martha) +- [handling conflict](https://merely-useful.tech/py-rse/teams.html#teams-conflict) +- [making all the above obvious to newcomers](https://merely-useful.tech/py-rse/teams.html#teams-documentation) + +For some other examples and inspirations of governance processes, consider the following: + +- [Martha’s Rules](https://journals.sagepub.com/doi/10.1177/088610998600100206) for discussing and deciding on issues in group meetings (if you cannot access the publication, see [Greg Wilson's explanation of Martha's rules](https://third-bit.com/files/2020/08/marthas/)) +- [GitHub's Minimum Viable Governance](/~https://github.com/github/MVG) (MVG) for establishing a lightweight governance process into free and open source projects that are run in version control systems. In MVG decisions are made through consensus of the project maintainers or determined based on the maintainers' consideration of a number of factors in "good faith"" (when explicit agreement of all maintainers cannot be reached). In reality, consensus-based governance can run you into trouble when you hit an issue where maintainers do not all agree but still want to make progress. Also, the definition of "good faith" is open to interpretation and leaves plenty of room for people, especially the powerful, to get away with acting in bad faith. A system based on voting and majorities may help you get around this issue. MVG is designed for a one organisation-many projects setup and is too elaborate for a single lesson project. However, it includes "boilerplate" template files for a steering committee, charter, governance, Code of Conduct documents, and language laying out a preference for consensus but with voting as a fallback, and other templates that may be helpful for those starting out and unsure about how to get on with establishing a governance process. +- [This list of resources related to community governance](https://docs.google.com/spreadsheets/d/1k8t1VPdcwKH7ZGaCA0q8NNxbFKQKkZGPth3nhfkKwAA/edit#gid=1287139202) from [The Center for Scientific Collaboration and Community Engagement](https://cscce.org) provides a collection of links to further reading material on this topic. It includes various guides, blog posts, and examples of community governance that may inform the discussions and decisions for your project. + +:::::::::::::::::::::::::::::::::::::::: keypoints + + +- GitHub's features **Issues**, **Mentions** and **Project Boards** can all be used to effectively communicate in a team of collaborators and manage a lesson development project. +- Slack and emailing lists provide communication channels outside of GitHub - for quick day-to-day messaging and more permanent discussions around lesson issues and development, respectively. +- Make sure to establish a governance model for your project early on - to describe the ground rules of participation and the process for decision making within the project. + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + diff --git a/25-wrap-up3.md b/25-wrap-up3.md new file mode 100644 index 000000000..ca034baa6 --- /dev/null +++ b/25-wrap-up3.md @@ -0,0 +1,31 @@ +--- +title: Wrap-up +teaching: 30 +exercises: 0 +--- + +Something to wrap up the whole workshop: +an exercise aimed at metacognition, +and a round of feedback e.g. one up one down. + +::::::::::::::::::::::::::::::::::::::: objectives + +- FIXME + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + +- FIXME? + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + + +:::::::::::::::::::::::::::::::::::::::: keypoints + +- First key point. Brief Answer to questions. (FIXME) + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..f146f90b9 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,11 @@ +--- +title: "Contributor Code of Conduct" +--- +As contributors and maintainers of this project, +we pledge to follow the [Carpentry Code of Conduct][coc]. + +Instances of abusive, harassing, or otherwise unacceptable behavior +may be reported by following our [reporting guidelines][coc-reporting]. + +[coc]: https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html +[coc-reporting]: https://docs.carpentries.org/topic_folders/policies/incident-reporting.html diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 000000000..fd52009af --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,83 @@ +--- +title: "Licenses" +--- +## Instructional Material + +All Software Carpentry, Data Carpentry, and Library Carpentry instructional material is +made available under the [Creative Commons Attribution +license][cc-by-human]. The following is a human-readable summary of +(and not a substitute for) the [full legal text of the CC BY 4.0 +license][cc-by-legal]. + +You are free: + +* to **Share**---copy and redistribute the material in any medium or format +* to **Adapt**---remix, transform, and build upon the material + +for any purpose, even commercially. + +The licensor cannot revoke these freedoms as long as you follow the +license terms. + +Under the following terms: + +* **Attribution**---You must give appropriate credit by: + - mentioning that your work is derived from work that is + Copyright © Software Carpentry, Data Carpentry, Library Carpentry, + or The Carpentries. + - where practical, linking to the respective lesson program website + (https://software-carpentry.org/, https://datacarpentry.org, https://librarycarpentry.org, or + https://carpentries.org), provide a [link to the license][cc-by-human] + - and indicate if changes were made. You may do so in any reasonable manner, but not in any way + that suggests the licensor endorses you or your use. + +**No additional restrictions**---You may not apply legal terms or +technological measures that legally restrict others from doing +anything the license permits. With the understanding that: + +Notices: + +* You do not have to comply with the license for elements of the + material in the public domain or where your use is permitted by an + applicable exception or limitation. +* No warranties are given. The license may not give you all of the + permissions necessary for your intended use. For example, other + rights such as publicity, privacy, or moral rights may limit how you + use the material. + +## Software + +Except where otherwise noted, the example programs and other software +provided by Software Carpentry and Data Carpentry are made available under the +[OSI][osi]-approved +[MIT license][mit-license]. + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +## Trademark + +"The Carpentries", "Software Carpentry" and "Data Carpentry" and their respective logos are +registered trademarks of [Community Initiatives][CI]. + +[cc-by-human]: https://creativecommons.org/licenses/by/4.0/ +[cc-by-legal]: https://creativecommons.org/licenses/by/4.0/legalcode +[mit-license]: https://opensource.org/licenses/mit-license.html +[ci]: http://communityin.org/ +[osi]: https://opensource.org diff --git a/config.yaml b/config.yaml new file mode 100644 index 000000000..498987240 --- /dev/null +++ b/config.yaml @@ -0,0 +1,61 @@ +#------------------------------------------------------------ +# Values for this lesson. +#------------------------------------------------------------ + +# Which carpentry is this (swc, dc, lc, or cp)? +# swc: Software Carpentry +# dc: Data Carpentry +# lc: Library Carpentry +# cp: Carpentries (to use for instructor traning for instance) +carpentry: "cp" + +# Overall title for pages. +title: "Collaborative Lesson Development Training" + +# Life cycle stage of the lesson +# possible values: pre-alpha, alpha, beta, stable +life_cycle: pre-alpha + +# License of the lesson +license: CC-BY 4.0 + +# Link to the source repository for this lesson +source: /~https://github.com/carpentries/lesson-development-training + +# Default branch of your lesson +branch: main + +# Who to contact if there are any issues +contact: team@carpentries.org + +# Navigation ------------------------------------------------ +# The menu bar will be in the following order: +# +# - Code of Conduct (CODE_OF_CONDUCT.md) +# - Setup (setup.md) +# - Episodes (episodes/) +# - Learner Resources (learners/) +# - Instructor Resources (instructors/) +# - Learner Profiles (profiles/) +# - License (LICENSE.md) +# +# Use the following menu items to specify the order of +# individual pages in each dropdown section + +# Order of episodes in your lesson +episodes: + +# Information for Learners +learners: +- setup.md +- pilot-description.md +- markdown-github-primer.md +- trial-runs.md +- reference.md + +# Information for Instructors +instructors: + +# Learner Profiles +profiles: + diff --git a/index.md b/index.md new file mode 100644 index 000000000..032b6a903 --- /dev/null +++ b/index.md @@ -0,0 +1,50 @@ +--- +site: sandpaper::sandpaper_site +--- + +:::::::::::::::::::::::::::::::::::::::::: prereq + +## Prerequisites + +Before joining Collaborative Lesson Development training, participants should be able to: + +- write formatted text - bold and italic, headings, links, bullet point and numbered lists - with Markdown. +- log into GitHub.com and create and edit files using the GitHub web interface. + +(See [A Primer on Markdown and GitHub](markdown_github_primer.html) for resources to help learn these skills. + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +::::::::::::::::::::::::::::::::::::: objectives + +## Learning Objectives + +After attending this training, participants will be able to: + +- collaboratively develop and publish lessons using The Carpentries lesson infrastructure: + lesson template, GitHub, GitHub Pages, etc. +- identify and characterise the target audience for a lesson. +- define SMART learning objectives. +- explain the pedagogical value of authentic tasks. +- create exercises for formative assessment. +- explain how considerations of cognitive load can influence the pacing, + length, and organisation of a lesson. +- configure and maintain accessible and usable lesson repositories using best practices, + readily available for collaboration. +- identify and correct accessibility issues in a Carpentries lesson. +- update and improve lesson material guided by feedback and reflection from teaching. +- review and provide constructive feedback on lessons. + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: questions + + + +:::::::::::::::::::::::::::::::::::::::::::::::::: + + + + diff --git a/instructor-notes.md b/instructor-notes.md new file mode 100644 index 000000000..434e335aa --- /dev/null +++ b/instructor-notes.md @@ -0,0 +1,5 @@ +--- +title: FIXME +--- + +This is a placeholder file. Please add content here. diff --git a/learner-profiles.md b/learner-profiles.md new file mode 100644 index 000000000..434e335aa --- /dev/null +++ b/learner-profiles.md @@ -0,0 +1,5 @@ +--- +title: FIXME +--- + +This is a placeholder file. Please add content here. diff --git a/links.md b/links.md new file mode 100644 index 000000000..89b603601 --- /dev/null +++ b/links.md @@ -0,0 +1,10 @@ +[blooms]: https://cft.vanderbilt.edu/guides-sub-pages/blooms-taxonomy/ +[carpentries-incubator]: https://carpentries-incubator.org/ +[carpentries-website]: https://carpentries.org/ +[dc]: https://datacarpentry.org/ +[github]: /~https://github.com/ +[hacker-2000]: https://doi.org/10.1037/0022-0663.92.1.160 +[kirschner-2006]: /~https://github.com/carpentries/instructor-training/blob/gh-pages/files/papers/kirschner-minimal-guidance-fails-2006.pdf +[lc]: https://librarycarpentry.org/ +[swc]: https://software-carpentry.org/ +[swc-lessons]: https://software-carpentry.org/lessons/ diff --git a/markdown-github-primer.md b/markdown-github-primer.md new file mode 100644 index 000000000..e74137780 --- /dev/null +++ b/markdown-github-primer.md @@ -0,0 +1,19 @@ +--- +title: A Primer on Markdown and GitHub +--- + +Before joining Collaborative Lesson Development training, +participants should be able to: + +- write formatted text - + bold and italic, headings, links, bullet point and numbered lists - + with Markdown. +- log into GitHub.com and create and edit files using the GitHub web interface. + +These skills can be learned by following two sections of the +[Building Websites with Jekyll and GitHub](https://carpentries-incubator.github.io/jekyll-pages-novice/) +lesson in [The Carpentries Incubator](https://carpentries-incubator.org/): + +1. [Introduction (starting from "Setting Up a Repository")](https://carpentries-incubator.github.io/jekyll-pages-novice/introduction/index.html#setting-up-a-repository) +2. [Authoring with Markdown (skipping the optional exercises)](https://carpentries-incubator.github.io/jekyll-pages-novice/markdown/index.html) + diff --git a/markdown_github_primer.md b/markdown_github_primer.md new file mode 100644 index 000000000..e74137780 --- /dev/null +++ b/markdown_github_primer.md @@ -0,0 +1,19 @@ +--- +title: A Primer on Markdown and GitHub +--- + +Before joining Collaborative Lesson Development training, +participants should be able to: + +- write formatted text - + bold and italic, headings, links, bullet point and numbered lists - + with Markdown. +- log into GitHub.com and create and edit files using the GitHub web interface. + +These skills can be learned by following two sections of the +[Building Websites with Jekyll and GitHub](https://carpentries-incubator.github.io/jekyll-pages-novice/) +lesson in [The Carpentries Incubator](https://carpentries-incubator.org/): + +1. [Introduction (starting from "Setting Up a Repository")](https://carpentries-incubator.github.io/jekyll-pages-novice/introduction/index.html#setting-up-a-repository) +2. [Authoring with Markdown (skipping the optional exercises)](https://carpentries-incubator.github.io/jekyll-pages-novice/markdown/index.html) + diff --git a/md5sum.txt b/md5sum.txt new file mode 100644 index 000000000..6e365e4fd --- /dev/null +++ b/md5sum.txt @@ -0,0 +1,38 @@ +"file" "checksum" "built" "date" +"CODE_OF_CONDUCT.md" "1ce82f3f04c2d64a36b4bbf0b22eb9e5" "site/built/CODE_OF_CONDUCT.md" "2022-02-01" +"LICENSE.md" "3e2c0d19ace00f148c3bfc2f403fc6c6" "site/built/LICENSE.md" "2022-02-01" +"config.yaml" "281cc09a01681dd58509a621747d50c1" "site/built/config.yaml" "2022-02-17" +"index.md" "89ed0f2f2b47849e343355f18954ddc8" "site/built/index.md" "2022-02-03" +"links.md" "52ab5103a5c90e5138a0b753d1c76d24" "site/built/links.md" "2022-05-30" +"episodes/01-introduction.md" "99e8e3f239e9c58a017323a6c6cfb17c" "site/built/01-introduction.md" "2022-02-25" +"episodes/02-lessons.md" "902df366d7ab495319747c89b54aadc0" "site/built/02-lessons.md" "2022-03-25" +"episodes/03-audience.md" "9fce0b46b4ebd19c3b02bea93bdea4b6" "site/built/03-audience.md" "2022-05-06" +"episodes/04-short-break.md" "05d1044278ce40ab59d9397db1f0e383" "site/built/04-short-break.md" "2022-02-01" +"episodes/05-objectives.md" "9c737e0a1597f82fa72b17039f41b197" "site/built/05-objectives.md" "2022-05-30" +"episodes/06-long-break.md" "3a4802231bb8e44cc6c132d86afb7f78" "site/built/06-long-break.md" "2022-02-01" +"episodes/07-infrastructure.md" "214a94c9f53145a0007c58b6d812cd08" "site/built/07-infrastructure.md" "2022-02-25" +"episodes/08-short-break.md" "05d1044278ce40ab59d9397db1f0e383" "site/built/08-short-break.md" "2022-02-01" +"episodes/09-formative-assessment.md" "59592d86c6c382b3c7427c6955fbf6c8" "site/built/09-formative-assessment.md" "2022-03-08" +"episodes/10-wrap-up1.md" "61b9a191133d1b45e877d203e79c256a" "site/built/10-wrap-up1.md" "2022-02-01" +"episodes/11-exercises.md" "50ed5c1c50689616240f571269e0bf0e" "site/built/11-exercises.md" "2022-05-26" +"episodes/12-short-break.md" "05d1044278ce40ab59d9397db1f0e383" "site/built/12-short-break.md" "2022-02-01" +"episodes/13-narrative.md" "99fcefde689166d559a35b497c3432a2" "site/built/13-narrative.md" "2022-04-28" +"episodes/14-long-break.md" "3a4802231bb8e44cc6c132d86afb7f78" "site/built/14-long-break.md" "2022-02-01" +"episodes/15-explanation.md" "80728b0e2ab8bf82e800654c31a53573" "site/built/15-explanation.md" "2022-02-23" +"episodes/16-short-break.md" "05d1044278ce40ab59d9397db1f0e383" "site/built/16-short-break.md" "2022-02-01" +"episodes/17-operations.md" "333fa7d483619d6fec87c0302b06f466" "site/built/17-operations.md" "2022-02-01" +"episodes/18-preparing.md" "8b4f8031d0ed457b5fdedf6177e3dbbd" "site/built/18-preparing.md" "2022-02-18" +"episodes/19-wrap-up2.md" "e2c7526c8f2a1572051c487457ba47f9" "site/built/19-wrap-up2.md" "2022-02-01" +"episodes/20-reflecting.md" "f5f307acbf0d39dd52fbb6354fdb060e" "site/built/20-reflecting.md" "2022-03-28" +"episodes/21-short-break.md" "05d1044278ce40ab59d9397db1f0e383" "site/built/21-short-break.md" "2022-02-01" +"episodes/22-external.md" "6317e9665cb5b5a7fc2411193a6672fa" "site/built/22-external.md" "2022-03-08" +"episodes/23-long-break.md" "3a4802231bb8e44cc6c132d86afb7f78" "site/built/23-long-break.md" "2022-02-01" +"episodes/24-collaborating.md" "80959a492fc25962651b80ed1adba7b4" "site/built/24-collaborating.md" "2022-02-25" +"episodes/25-wrap-up3.md" "4601673357625bfcd0b614554835aa2c" "site/built/25-wrap-up3.md" "2022-02-01" +"instructors/instructor-notes.md" "60b93493cf1da06dfd63255d73854461" "site/built/instructor-notes.md" "2022-02-01" +"learners/setup.md" "7cba8e7643995a764eaf4b269369c99a" "site/built/setup.md" "2022-03-04" +"learners/pilot-description.md" "e33e8c3e3df21a170f32532607a22de8" "site/built/pilot-description.md" "2022-03-30" +"learners/markdown-github-primer.md" "103cfbb156526a6d29ed681f2de216c0" "site/built/markdown-github-primer.md" "2022-02-03" +"learners/trial-runs.md" "82469eccef779a5fe0dedc706076593e" "site/built/trial-runs.md" "2022-02-01" +"learners/reference.md" "25f7dae64fcea529b6a83f7d4ff9b1b1" "site/built/reference.md" "2022-02-01" +"profiles/learner-profiles.md" "60b93493cf1da06dfd63255d73854461" "site/built/learner-profiles.md" "2022-02-01" diff --git a/pilot-description.md b/pilot-description.md new file mode 100644 index 000000000..d9e00c5fb --- /dev/null +++ b/pilot-description.md @@ -0,0 +1,48 @@ +--- +title: Collaborative Lesson Development Training Pilot Description +--- + +**13-16 June + 27&28 July 2022** + +## Trainers + +- Dr Aleksandra Nenadic, Training Lead at The Software Sustainability Institute +- Dr Mateusz Kuzak, Training Program Lead, The Netherlands eScience Center +- Dr Sarah Stevens, Data Science Facilitator, University of Wisconsin-Madison +- Dr Toby Hodges, Director of Curriculum, The Carpentries + +## About this training + +_Collaborative Lesson Development Training_ is a new program being piloted by The Carpentries, +teaching the skills required to collaboratively create open source lessons using The Carpentries infrastructure. +The training will focus on three main topics: + +1. Good practice in lesson design and development +2. Creating lesson websites with The Carpentries Workbench +3. Collaboration skills + +Spread over six half-days, with an extended break between sessions 4 & 5, +participants will learn how to prepare an effective lesson to suit a defined target audience, +how to implement that lesson as an open source website using The Carpentries lesson infrastructure, +and how to collaborate and build community around a lesson project. +Participants will apply these principles as they are introduced during the training, +creating a sound foundation for their lesson in a series of hands-on exercises, +trialling newly-developed content, and preparing their lesson repository for collaboration. + +## Who is this training for? + +The pilot is aimed at teams of 2-4 people, wishing to collaborate on a new lesson. +At least one member of each team should be a certified Instructor, +having completed The Carpentries Instructor Training, +or another training covering similar topics, e.g. an RStudio Instructor. + +## Format & application + +This training will take place virtually, combining video and screen sharing on Zoom +with a collaborative notetaking document for sharing notes, responses to exercises, and links to further resources. +The first pilot will take place 13-16 June 2022 ([12:00-16:00 UTC](https://www.timeanddate.com/worldclock/fixedtime.html?msg=Collaborative+Lesson+Development+Training+Pilot+1&iso=20220613T12&p1=1440&ah=4)) and 27&28 July 2022 ([12:00-16:00 UTC](https://www.timeanddate.com/worldclock/fixedtime.html?msg=Collaborative+Lesson+Development+Training+Pilot+1%2C+pt2+&iso=20220727T12&p1=%3A&ah=4)). + +There is no fee to join the pilot, but spaces are limited. +To apply to participate in the training, please fill out this short form: https://forms.gle/9ZXZEjgJGWNQmxY47 + +For more information and to ask questions, please contact [Toby Hodges](mailto:tobyhodges@carpentries.org) diff --git a/reference.md b/reference.md new file mode 100644 index 000000000..c9f817655 --- /dev/null +++ b/reference.md @@ -0,0 +1,8 @@ +--- +title: Reference +--- + +## Glossary + +FIXME + diff --git a/setup.md b/setup.md new file mode 100644 index 000000000..5d3c9f8aa --- /dev/null +++ b/setup.md @@ -0,0 +1,9 @@ +--- +title: Setup +--- + +Before joining this training, +participants should have a [GitHub](https://github.com) account. +[Detailed instructions on how to create a GitHub account can be found +in the GitHub Docs pages](https://docs.github.com/en/get-started/signing-up-for-github/signing-up-for-a-new-github-account) + diff --git a/trial-runs.md b/trial-runs.md new file mode 100644 index 000000000..794217120 --- /dev/null +++ b/trial-runs.md @@ -0,0 +1,6 @@ +--- +title: "Lesson Trial Runs" +--- + +TODO +