The Carpentries is preparing to retire this handbook at the end of 2023. Existing content that has not already been replicated elsewhere will be relocated. See the relevant issue on the source repository for more details.

D Lesson Sprint Recommendations

One way of making progress and encouraging collaboration on the development of a lesson is to organise a dedicated event such as a co-working session or a lesson development sprint. A co-working session is typically a shorter, less formal event bringing people together to work simultaneously on the lesson. The co-working session might include brief check-ins for the group to discuss progress and next steps, but most of the time will be spent working on the lesson independently or in small groups. A sprint is typically a longer, more structured event designed to welcome and bring onboard new contributors to the lesson project.

D.1 Introduction

The following set of recommendations, written by members of The Carpentries community, is intended to guide lesson authors through the process of organising a lesson sprint. The recommendations are relevant to a lesson sprint consisting of a single session or in multiple sessions with breaks between, whether on one day or multiple consecutive days. We have tried to note where a particular recommendation is only relevant or particularly relevant to a sprint being run across multiple days/sessions. These recommendations were written with a particular focus on sprints taking place virtually, i.e. with participants meeting by video conference, but many of the recommendations (especially those in the Before and After sections) are also relevant to in-person events.

D.1.1 Target Audience

The target reader is one of the lead developers/maintainers of a lesson under active development e.g. in The Carpentries Incubator. They should already have a clear idea of the target audience and main learning objectives for their lesson, even if they haven’t started writing the actual material yet - see the Planning your lesson section for more details of the steps we recommend you take with your lesson before it is time for a sprint. They may be planning to teach the lesson for the first time, or have recently taught it for the first time, and now want to improve the lesson material based on feedback collected when teaching.

If you in the stage where you are not yet clear on the target audience or the overall learning objectives for your lesson, we suggest you work through the Deciding what to teach chapter of this handbook before returning to this guide.

D.1.2 Objectives

Provide practical tips and more theoretical guidance about how to:

• organise an inclusive and accessible sprint
• make the most of a dedicated lesson sprint
• create coherent lesson material from individual contributions made during the sprint
• engage contributors before, during, and after the lesson sprint

D.2 Before the Sprint

• Establish an organising committee. Organising the sprint will be much easier if there are multiple people involved in planning and running the event. Aim to establish an organising committee with members from diverse backgrounds who can bring a broad perspective to create an accessible and inclusive event for your participants. If you have more than 2 people, be sure to assign roles and responsibilities to avoid diffusion of responsibility.

• Select a code of conduct. If your lesson repository already has a code of conduct, apply it to the sprint and associated events too. If your lesson repository does not already have a code of conduct, add one. Like licenses, we do not recommend that you write your own code of conduct from scratch. Instead, re-use/adapt an existing text you find online. We recommend The Carpentries Code of Conduct, which was designed with exactly these kinds of project in mind. Assign at least one person as the contact person/facilitator for matters relating to the Code of Conduct, and make sure all sprint participants are aware of who this is and how they should connect with them. You can do this by including their details in the “primer” information you provide to participants before the event and by introducing them when you mention the code of conduct at the start of the sprint itself.

• Set up a planning meeting/call for the committee Use this meeting to agree on the dates, event format and the target audience in sufficient detail and high-level objectives of your sprint. Document your discussions and plans in a central location so that everyone involved in the process can access them. Divide responsibilities to put together resources (such as for communication and norms) that will be shared with all participants. (See below for more details.)

• Consider participants’ roles and expertise.

  • Do you have a team with diverse skillsets and topic knowledge required to meet your high-level objectives? If not, consider finding and inviting other people.

• Establish communication channels and norms. This will set an expectation for how collaborators will communicate before, during, and after the sprint.

  • Dedicated messaging channels have been used with success for conversations/short updates during the sprint and in-between sprint conversations. See During the Sprint for more details.
  • Mailing lists for initial organisation and other important and more permanent communication, e.g. scheduling meetings.
  • [Online] Video conferencing technology that is an accessible choice for everyone and suitable for the format of the sprint.
  • Decide on the basic etiquette for participation, such as how to collect ideas, who to contact for support, how to participate in an ongoing discussion, how to contribute to content development and how to review contributions.
  • Choose a collaborative note-taking platform for recording and communicating decisions, minutes and actions from meetings. (See the tools section for details of some different note taking platforms.)

• Think about the timing of your sprint.

  • You can run the sprint in conjunction with an upcoming event, e.g. a conference/meeting that many in your community will already be engaged with. If you would like to attract new contributors, this will make it easier to get people’s attention and convince them to block time in their calendar to join in with the sprint. You may also be able to tap into the promotional communications etc. for that event, and/or invite people to join the sprint, e.g. via a lightning talk or poster.
  • Conversely, you may want to avoid clashes with another event if your team is going to be engaged elsewhere or have other commitments.
  • Announce the dates for your sprint at least 6 weeks in advance.

• Add dates and time in your calendar: In addition to the event dates, schedule a few planning meetings with the committee members before the sprint and one meeting/co-working session after the sprint for wrap-up/follow-up tasks.

  • When possible, offer a pre-event onboarding call that can be used for sharing all the relevant resources and setting expectations around what to expect at the event.

• Scope out what content will be worked on. Defining objectives and which sections/aspects of the lesson should be worked on during the sprint will reduce the energy/time required for contributors to begin working and help to keep efforts focused during the event. This guidance might be in the form of a list on a shared document or open issues on the lesson repository and do not need to contain much detail. You do not need to micromanage individual contributions, but a summary of each key objective can serve as a starting point for discussions between collaborators about the best approach to reach those goals.

• Create a resource for good practices for lesson design. This resource should be shared with all the participants to assist them in designing lessons to be as effective as possible. Consult the rest of this Handbook for recommendations that you and your collaborators can follow when creating the lesson material during the sprint.

• Prepare a video call link for all sprint sessions. [Online] If your sprint is taking place across multiple sessions, or will include multiple video calls between participants, try to provide a single meeting link for them all. This will save contributors time when returning to the sprint calls, e.g. for a check-in session or after a break.

• Communicate participation information and send reminders before the Sprint

  • Send short reminders a week and a day before the Sprint, with time and date, video conferencing URL, note docs and any prior preparation work
  • If prior reading/preparation is required, give at least a week lead time
  • Think of a way to let participants withdraw their participation/leave early/join late comfortably; this helps especially for folks juggling with multiple responsibilities

• Use time zone-converted event links for remote participants. [Online] For sprints running online with the potential for participants from multiple regions/time zones, it is vital to announce time(s) and date(s) for your sprint in a way that allows visitors to see the equivalent in their local time. Always list event timings in UTC and use tools like timeanddate.com to provide an automatic conversion to local time.

• Promote the sprint widely. You might want to promote your upcoming sprint to attract contributors beyond your current team.

  • You can use mailing lists, Slack channels, Newsletters, Twitter and direct invitation to reach your desired participant groups.
  • When possible, offer financial support to people who may want to participate but may have special needs to facilitate their participation for the duration of the event (for example, childcare for in-person, high-speed internet for remote events).
  • Consider whether you need a system to track participation for the Sprint, e.g. a Google Form/Eventbrite page
    • You may not need this if you already have dedicated communication channels (see “establish communication channels and norms”) and the Sprint is open to everyone in those channels
    • You may want to collect additional information from participants, e.g. if there are multiple parallel discussion topics, which discussion they’d like to participate in; dietary requirements and emergency contact information for in-person events; accessibility needs and time zone for virtual events
    • Tools like Eventbrite allow organisers to easily send emails to all attendees, e.g. reminders and follow-ups.

• Prepare a “sprint primer” document and publish it. Provide participants in advance with a single document that provides all the information they need to know before joining (or deciding to join) the sprint: what steps do they need to take to register, to attend/connect, to prepare? What can they expect when they join? What will the format be? What roles will there be within the group? In what different ways can participants contribute during the sprint? What channels will be used for communication? What is the schedule? Take everything you have been preparing from the other recommendations in this list and put all that information into this document so your (potential) participants can refer to it before and during the sprint. See this primer document from the CarpentryCon@Home 2020 sprint on the Library Carpentry FAIR Data and Software lesson.

There is a number of tools that in combination could be used for running effective curriculum development sprints - we cover a good number of tried and tested technologies under the tools section.

D.2.1 Before The Sprint: Recommendations for GitHub

• Review open issues on your lesson repository before the sprint and consider flagging (labelling) existing issues and opening new ones to describe tasks that could be tackled during the event. GitHub Projects can help with this, allowing you to label particular issues within scope for the sprint and even organise them further into categories to help contributors find something to work on. Even if you cannot invest time into managing issues to this extent, make sure open issues include all the contextual information necessary for a new or part-time contributor to understand what needs doing and whether they can help.

D.3 During the Sprint

• Enable access to documents for shared note-taking. When possible store all the shareable documents in a central repository or shared drive so they are easy to find. One main document should be created to share links to all the resources that will be used for the sprint. This document should be kept visible to all participants and persist beyond the end of the sprint.

• Run a “sprint primer” session. A primer session helps contributors get oriented with the structure of your lesson and its associated repository, the setup required to work on the lesson (e.g. local builds to preview lesson webpages), and the communication channels that will be used during and in-between the sprint sessions. You could run this primer session a week or two days before the sprint begins. This can also be the first session of the sprint event before co-working sessions begin.

• Start the video conference call 10 mins ahead of official start time. [Online] To allow newcomers and first-time participants to get familiar with tools, test audio and video set up, warm up, etc.

• Record information about participants and contributions.

  • Start your event by asking people to sign-in to the shared document by providing names, ORCID identifiers, GitHub usernames, and any other identifiers/handles that can be used to acknowledge their contributions. You can also ask you the participant to optionally provide their pronouns to ensure that everyone is addressed with their preferred pronouns.
  • When working on an online repository, you can use issues to describe and assign tasks. This can also be directly done on the shared notes that everyone has access to. This helps to avoid duplication of effort during the sprint, and gives participants a way of coordinating additional discussions among themselves where appropriate to make progress on a task.
  • Prompt participants to add their details to the shared notes, so you can refer to it later and ensure everyone’s contributions are recorded and proper credit is given when publishing the lesson.

• Divide co-working sessions with scheduled check-ins Plan your sprint to have several co-working sessions that are followed by check-ins or report outs to allow contributors to reflect on their progress. This will also allow them to share what they’ve achieved, what’s blocking their progress, where they would like some feedback and what they intend to do next. We recommend using a web-based shared clock such as cuckoo.team to keep track of co-working, share-out and breaks.

• Record the check-ins. If technically possible, and provided all participants consent, record these check-ins (video or written) so that those who could not join can catch up on the latest progress when they (re-)join the sprint. This is particularly important for sprints taking place across multiple sessions/days and/or a wide range of time zones. These check-in discussions can end by taking extensive notes in the shared document.

  • Assign roles for check-ins. To ensure everyone has an equal chance to contribute to the discussion and the sprint, the lead organiser(s) should assign meeting roles for the check-in calls. To further promote equity of participation, these roles should be rotated for each day of the sprint, or each separate sprint event. Roles may include:
    • a Facilitator who coordinates the discussion and keeps it moving, watching out for raised hands and making sure those with something to contribute get the chance to do so;
    • a Timekeeper who monitors the time remaining for the check-in and ensures that all topics are covered in a timely fashion. The Timekeeper prompts the Facilitator/speaker to move on when necessary to cover everything.
    • an Issue/Task Creator, who keeps track of actions that arise from the check-in discussion and creates an issue or describes the task in the shared notes.
    • a Notetaker, who takes minutes of what is discussed in the check-in. In some instances, it may be possible to combine the roles of Notetaker and Task Creator.

• Consider participants’ roles and expertise.

  • Consider the power dynamics in the group, e.g. if you have PIs and early-career PhD candidates participating, have seperate breakout rooms for each of those groups so participants can comfortably discuss with peers (but report out at the end so folks can learn from other perspectives), have a moderator who keeps track how much folks are speaking and provide space and (gentle) prompts to encourage the lesser-spoken folks to speak, etc

• Use a chat channel for communication outside check-ins. To allow participants to “unplug” from video calls/move to separate locations for the bulk of the sprint, use a text-based chat such as Slack or Gitter for discussion when not checking in. If your chosen platform allows it, minimise global notifications to sprint participants by making use of threaded conversations. This will allow contributors to focus on their chosen task unless involved in a conversation directly relevant to them.

• Prepare breakout rooms for small group discussion and co-working between check-ins. [Online] Open a small number of break out rooms for sprint participants to use during working sessions. This allows the participants to self-organize if they need to discuss something they are working on or co-work on a particular task. In Zoom, select the option to “Let participants choose room”. For [in-person] sprints, prepare an equivalent set of different rooms/locations for participants to gather and discuss in smaller groups without fear of disturbing the whole team.

• Provide a way for contributors to mark their work ready for review. If you prefer to require material is reviewed before being included in the lesson, give participants a way to signal when their contributions are ready. You might consider providing guidance/assigning responsibility for reviewers of particular sections/types of contribution. If your lesson is being developed on GitHub, see the section below for more specific recommendations.

• Reviewing contributions. Allocate 1-2 sessions in the sprint to review and approve contributions made by others. If this is not planned in the event, sprints may end with an influx of new material as contributors finish up what they were working on as the event closed. Make sure that each contribution is reviewed and if possible (and where appropriate), merged into the lesson. This allows contributors to leave the event with a sense of accomplishment from the sprint, and ties up any loose ends before new tasks are taken on to develop the material further. If the participants who were originally assigned to review have had to leave before the review session, the organisers should delegate the review task to those who are available and willing to help finish the review process on time.

• Ask for feedback. Allocate a short feedback session before closing the event. Feedback should be kept short and recorded anonymously via a feedback form or shared document (that does not require signing in). Ask your participants to reflect on the event in terms of what worked and what can be improved.

D.3.1 During the Sprint: Recommendations for GitHub

• Consider running a skill-up session for contributors. Depending on their previous experience with the platform, contributors may benefit from learning/being reminded how to use GitHub, working on branches/forks, and the associated tools on their local system. Providing a session/resources on this will also make your sprint less intimidating for newcomers to lesson development, which may increase participation. GitPod may offer a way for participants to contribute to the lesson without the need for setting up a local development environment. As with the “primer” session mentioned above, this skill-up may fit best at the beginning of the sprint. This can also run as a separate event that takes place in the days leading up to the full sprint.

• Flag pull requests as a draft and ready for review as you work. Opening draft pull requests early, while work on a task is ongoing, can help contributors understand where progress is being made and identify tasks/issues that still need to be tackled. Marking pull requests as ready for review helps maintainers prioritise their focus during the sprint and maintains momentum by ensuring that completed work is merged into the lesson as soon as possible. Opening draft pull requests is particularly important at the end of a sprint, to capture progress up to that point even if a task hasn’t yet been completed.

• Plan who will review pull requests. Make a plan for who will review each pull request (PR). As a group, you can create a list of reviewers by subject so the person who opens the pull request knows who is interested and capable of reviewing and can request a review accordingly. Alternatively, you may decide on a circle of reviewers. E.g. Aaliyah reviews Juan’s PRs, Juan reviews Alex’s PRs, and Alex reviews Aaliyah’s PRs. Another option might be to ask for a reviewer when planning who will do the task. For particularly small groups where reviewing is more likely to become a bottleneck, or in cases where the main objective of the sprint is to create quantity rather than quality, you may decide it is acceptable for contributors to merge their own pull requests.

• Link pull requests to open issues. Mentioning open issues in pull requests (even when a work in progress) informs people about which issues are being worked on. As mentioned in the point above, this is particularly useful to ensure progress can continue on the lesson after the sprint has finished.

• Record contributions that do not (directly) result in commits. Some participants may be more comfortable writing material on a different platform e.g. Google Docs, which is later transferred to GitHub by someone else. Make use of GitHub’s commit co-author feature where possible or, if the author does not have a GitHub account, make sure their name and other details are included in your README, AUTHORS, or any other listing/metadata about contributors to the project (.zenodo.json, .allcontributorsrc, etc).

• Review open pull requests. At the end of the sprint, organisers should ensure that any pull requests marked as ready for review are processed and (where appropriate) merged, so that these contributions are not forgotten or left to go stale before changes can be requested.

D.4 After the Sprint

• Celebrate the progress. Though lesson development is an iterative process, every contribution counts towards the completion of a lesson. It is, therefore, important to celebrate the progress you and your colleagues make at the lesson development sprint. Take a break (if you can) before meeting the organising committee for a debrief call.

• List completed and outstanding tasks. Create GitHub issues or share a document to highlight the status of different tasks. Set a deadline for the completion of outstanding tasks to share online with all the contributors. These will help you and other contributors understand the next steps when working together on the lesson as well as continue working on the lesson asynchronously.

• Plan the next steps! Review the shared documents from the sprint and highlight successes and place for improvements to include in a report. Feedback and reflections from running a sprint often inform a new set of changes and updates to be made in the event format or lesson material, discuss and document those for planning the next events. Plan to host a periodic co-working call to keep collaborators engaged or schedule the next sprint to ensure that momentum is maintained on the lesson.

• Write up a report and share it with your contributors. A summary of progress made and next steps (with links to open issues/work-in-progress pull requests) will help you and your contributors appreciate the progress made during your sprint, and encourage efforts on the lesson to continue. Consider turning this overview into a blog post to share your experience and achievements with the wider community!

• Contribute to these recommendations. While organising and running your sprint, did you find any useful resources or steps not already covered in this guide? Do you have any advice or guidance for others who may follow these recommendations in future? If so, please contribute back to improve this resource! To tell us about changes you would like to see to these recommendations, please email the authors (tobyhodges@ carpentries.org), open an issue or contribute your changes directly in a new pull request.

D.4.1 After the Sprint: Recommendations for GitHub

• Capture outstanding tasks in new issues on the lesson repository. You may also wish to assign these to specific contributors for follow up after the sprint.

• Label issues to encourage asynchronous contributions. Issue labels, such as “help-wanted” and “good-first-issue,” provide valuable information to potential contributors about where their contributions could be most valuable and how they could begin to get involved with developing your lesson. Issues labelled “good first issue” will appear automatically on the /contribute page of your repository, providing a quick overview of ways to get involved that have a low barrier for entry. Other labels can be used in a similar way to automatically display listings of issues to potential contributors. For example, The Carpentries publishes a Help Wanted page that provides their community with an overview of open issues with the “help-wanted” label on many of their repositories.

• Clean up branches on your repository. Sprints often leave behind a large number of merged branches that can be removed from the lesson repository. Minimising the number of “stale” branches reduces clutter on your repository, allows contributors to name their branches without fear of an unintentional clash and helps people working with local branches.

D.5 Tools and Resources

• Cuckoo is a shared countdown timer for collaborative co-working sessions. Create a page and share the URL with your contributors; everyone connected to the page will be notified when the set countdown ends. Shared timers such as this can be useful to help coordinate sprint sessions between check-ins.
• GitPod provides a cloud-based development environment for projects. The service can deliver an interactive development environment for a project on GitHub, with dependencies and environment setup already taken care of, allowing contributors to begin working on a project without needing to deal with this overhead on their local machine. The GitPod documentation provides instructions to configure your project to use the service.
• Shared note-taking tools:
  • Etherpad provides a relatively simple shared note-taking interface. Useful features include colouring to differentiate contributions from individual participants, an integrated chat window, and line numbering. Open Etherpad services include FIXME
  • HedgeDoc (formerly CodiMD) provides an interface for collaborative writing in Markdown. Useful features include a split-panel view for simultaneous editing and previewing, built-in support for concept mapping with GraphViz and Mermaid.js, and line numbering. The Carpentries provides a CodiMD instance for use in activities and events relating to their community, and HackMD and Cryptpad provide similar, free services to a general audience.
  • Google Docs provides an interface for collaborative writing similar word processing software such as Microsoft Word. Useful features include threaded comments, a mode for suggesting changes instead of directly editing the document, and visual formatting without the need for text markup.
• timeanddate.com provides many services related to conversion between time zones. Useful features include a meeting planner suggesting suitable times for events with attendees in multiple regions, an event announcement system displaying the start time and date of an event converted to the visitor’s locale, and a time zone converter to check what time it is right now in another location around the world.
• Google Calendar and other timezone-aware calendar applications can be used to create entries for your event that will automatically display in the local time of the person viewing the page/entry. Alongside listing event times in UTC with a link to timeanddate.com (see above), timezone-aware calendar events are essential to make your sprint inclusive to an international community.
• The Carpentries Curriculum Development Handbook provides an overview of the backwards design approach recommended for lesson development by The Carpentries. It includes guidance on identifying the target audience of your lesson, defining meaningful learning objectives, designing appropriate examples and exercises, and the various stages of the lesson life cycle.
• Slack provides a workplace messaging platform for threaded text discussion. Useful features include multiple open and private channels, document and image sharing, and a wide range of plugins to interface with other systems. Some features require a paid subscription. Members of The Carpentries community can create a channel for discussion around development of their lesson in the organisation’s Slack workspace
• Gitter is another instant messaging service. It lacks some of the features of Slack but does not require a paid plan to remove limits on usage and it integrates well with GitHub, e.g. by allowing references to particular repositories, issues, and pull requests.

These and many other tools that could be useful for organising and running your sprint are also described in the Tools for Remote Collaboration chapter of The Turing Way.

D.6 Acknowledgments

These recommendations were originally developed in a separate GitHub repository by Steve Crouch, Toby Hodges, Zhian Kamvar, Aleksandra Nenadic, Malvika Sharan, Sarah Stevens, and Emmy Tsang. Ideas, suggestions, and guidance were provided by Sarah Alidoost, Chris Erdmann, Kristina Hettne, and Liz Stokes.

D.7 Further Reading

• The Guide for Collaboration section of The Turing Way has many more recommendations and guides to help your team collaborate effectively. Many other sections of the book are also relevant.
• The Turing Way’s process for organising and running a Book Dash has many similarities to the recommendations made here for lesson sprints. We recommend that you explore this resource, which also includes checklist and schedule templates that could fit a lesson sprint with some minor adjustments.
• In addition to the rest of this Handbook, Greg Wilson’s Teaching Tech Together provides a more in-depth overview of the reverse design approach to lesson development as well as many useful pointers for teaching and collaborating.
• The Carpentries Instructor Training curriculum is another valuable source of advice for writing and teaching lessons.

Ambrose, Susan A, Michael W Bridges, Michele DiPietro, Marsha C Lovett, and Marie K Norman. 2010. How Learning Works: Seven Research-Based Principles for Smart Teaching. John Wiley & Sons.

Jordan, Kari, François Michonneau, and Belinda Weaver. 2018. “Analysis of Software and Data Carpentry’s Pre- and Post-Workshop Surveys.” https://doi.org/10.5281/zenodo.1325464.

Wilson, Greg, Jennifer Bryan, Karen Cranston, Justin Kitzes, Lex Nederbragt, and Tracy K. Teal. 2017. “Good Enough Practices in Scientific Computing.” PLOS Computational Biology 13 (6): 1–20. https://doi.org/10.1371/journal.pcbi.1005510.