Checklist#

  • For Instructor / Facilitator

  • For Reviewing content

    • Pedagogy

    • Content

    • Grammar

Module Checklist (FOR INSTRUCTOR)#

ReadMe#

The Readme for each workshop should contain the following:

An H1 level heading with the name of the tutorial#

Contact information#

  • Who is teaching this workshop?

  • What SMU unit are they in?

  • What is their contact information?

Learning Prerequisites#

  • What prerequisites are required to get the most of out of this workshop?

  • What are participants already expected to know?

Technology Prerequisites#

  • What are the technology requirements for the workshop?

  • Is it online?

  • Will they need to install any software on their laptop?

  • Do they need to make sure they have administrative permissions for this laptop?

Learning Objectives#

  • What will they learn in this workshop?

Description:#

  • A short paragraph with an accessible description of the technique.

  • Table of contents with links to the topics in the tutorial.

Modules#

  • Introduction: Describes the technique or technology in more detail, ideally also explaining the purpose or value of the approach

  • Pages: Each major concept or milestone in the tutorial should have a new page.

  • Code segments should be denoted using the markdown syntax for code and interspersed with explanations. Large blocks of unexplained code should be avoided, but if they’re necessary link to a raw text file or Jupyter notebook within the explanatory text.

Resources (or continue page?)#

  • If applicable, a resources section with links to sources, books, tools, or other tutorials at the end of tutorial.

Attribution#

Free and Open Source Code#

In general, it’s not necessary to provide in-line citations in the materials for a technical workshop unless you’re using someone else’s exact prose or you’re replicating a significant, non-trivial section of code. For example, code segments found on Stack Overflow do not need to be cited unless you think it’s pedagogically helpful. However, if you build your session around replicating a significant portion of a particular application, you must consider the license under which that software is released and consider providing attribution, even if attribution is not required under the terms of the license. In general, free and open source code licenses do not require attribution, but using a large portion of the code may require replicating the license. Check a summary of the terms of the license (or the license itself, if you’re feeling adventurous) if you decide to replicate a significant portion of an open-source project in your session.

Citation practices for workshops#

Many of the workshops in this curriculum were created by multiple creators. This makes the process of attributing of each other a bit messy. An interested person can see the precise details what was done and by whom in what order in the GitHub commit log. However, we also realize that folks reading this curriculum may not be Git-literate (yet!) or may access this curriculum as a .PDF or a hard copy document offline. Thus, it is also important to attribute the labor of individual contributors in written form at the beginning of each workshop and every other section of this curriculum.

Currently, the workshops include two forms of attribution: “Session leader: …” and “Based on previous work by …”—the former indicates the person who will be the lead teacher of the workshop during the Summer 2020 DHRI session, and the latter indicates who worked on the content of the workshop. We recognize that both are significant attributions, but that the latter is especially important in terms of citation politics, particularly for students and junior scholars. So, despite its redundancy, we listed a contributors name twice if they both are leading the workshop in June 2018 and if they created or significantly contributed to or revised the workshop’s content. It is also of note that various contributors edited the content of each others’ workshops.

In regards to citing other academics, this curriculum aims to follow commonly held academic citation practices, in which direct quotations are formatted and cited as such, and when another scholar’s ideas or concepts are referenced, a citation is also included. In general, the following citation information is provided: the author name(s), publication title, and publication date, and a hyperlink to the source, if applicable and within copyright.

Planning#

Helpers#

  • How many instructors are needed? For the hands on components, are additional instructors or helpers required?

Calendar#

Marketing#

  • Submit ticket to Marketing department to promote event. DESCRIBE or LINK TO PROCESS

  • Inform Director of Fondren or anyone else that needs to know about the event.

Assessment#

  • Create post-survey(s) to be sent to participants. DESCRIBE or LINK TO PROCESS

  • Send after workshop or after each day of multi-day workshop.

  • EXAMPLE CHECKLIST FOR REVIEWER OUR FINAL MAY BE DIFFERENT. We will write this last

Review#

As our goal is that our lessons build on each on each other. We will review lessons for content and where they fit in to other workshops.

Process of Review#

Creation of these workshops is collaborative and review is an iterative process. We will review for: Pedagogy, Content and grammar.

Grammar#

Check all spelling and punctuation throughout. All bulleted lists should end in some type of end mark (period, question mark, etc.). Read through all content to make sure sections or content is not duplicated or repetitive, or that there are not disruptive jumps from one topic to another without explanation.

Checklist for review: Reviewers will assess#

Content: Are the following sections defined?#

  • ReadMe

    • Contact information

    • Prerequisites

      • Learning

      • Technology

    • Learning objectives

    • Description

    • Table of Contents

  • Citations

  • Modules

    • Are pages of similar length?

    • Does the content flow well?

    • If a resources page is helpful, has it been included at the end of the module?

  • Planning: Have these things been accomplished?

    • Calendar

    • Marketing

    • Assessment

Pedagogy: Does each module fulfill#

  • Scope

  • Scaffolding

  • Purpose

  • GitHub coding

    • Is the structure consistent with the style guide?

    • Do all modules have working Previous/Next links at the top and bottom of each page?

    • Have all links embedded in the module been tested and updated or removed as necessary?

Grammar#

  • Check all spelling and punctuation throughout.

  • All bulleted lists should end in some type of end mark (period, question mark, etc.).

  • Read through all content to make sure sections or content is not duplicated or repetitive, or that there are not disruptive jumps from one topic to another without explanation.

  • Mark and ask Instructor about sentences where wording might be changed to improve comprehension.

Every module in the curriculum should have these elements:

  • Location

  • A dedicated repository on GitHub

  • While you have the option to create tutorials under your own name on GitHub, when finished or when you reach a major milestone with your tutorial, request (ADD PROCESS) fork it to the Research Services and Workshops account on GitHub for reference by future instructors.

  • Includes

  • A README.md file.

  • Four elements present in the README.md file:

    • a h1 level heading with the name of the tutorial

    • a short paragraph with an accessible description of the technique

    • a short paragraph with the goals or outcomes of the workshop

    • a table of contents with links to the topics in the tutorial

  • An introductory page describing the technique or technology in more detail, ideally also explaining the purpose or value of the approach

  • A page or pages with installation or setup instructions

  • A page or set of pages for each major concept or milestone in the tutorial.

  • “<<< Previous” and “Next >>>” buttons on each page that indicate the path a reader will take through the tutorial.

  • Code segments should be denoted using the markdown syntax for code and interspersed with explanations. Large blocks of unexplained code should be avoided, but if they’re necessary link to a raw text file or Jupyter notebook within the explanatory text.

  • Pedagogical considerations

  • The tutorial should ideally build incrementally toward a larger goal or project and produce some kind of product, whether a visualization, webpage, repository, analysis, app, or draft writing/proposal. The tutorial should be iterative and purposeful—don’t just cover material to cover material.

  • When possible, prefer techniques or approaches from other tutorials.

  • Everything substantially covered verbally or through slides in a tutorial should appear in the markdown version. Someone not present at the event or who can not hear or see the materials presented should still, in theory, be able to follow based on the materials provided in the markdown tutorial.

  • If many topics or headings are included in the tutorial (more than 6), the markdown files other than the README.md should be placed in a folder within the repository labelled sections or similar and linked from there. (Having too many files in the files section on GitHub looks messy and is visually overwhelming.)

  • Hyperlinks

  • Have all links embedded in the module been tested and updated if necessary, or removed if necessary?