carpentries/training-template

Template for instructor training workshop websites.

training-template

This repository is The Carpentries' template for creating websites for Instructor Training workshops.

1. Please do not fork this repository directly on GitHub. Instead, please use the instructions below to copy this training-template repository and customize it for your workshop.

2. Please do your work in your repository's gh-pages branch, since that is what is automatically published as a website by GitHub.

3. Once you are done, please send your repository's URL to The Carpentries' administrator. We build the list of workshops on our websites from the data included in your index.md page. We can only do that if you [customize][customization] that page correctly and send us a link to your workshop website.

If you run into problems, or have ideas about how to make this process simpler, please get in touch. The pages on [customizing your website][customization], the FAQ, and the [design notes][design] have more detail on what we do and why.

Creating a Repository

1. Log in to GitHub. (If you do not have an account, you can quickly create one for free.) You must be logged in for the remaining steps to work.

2. On this page (https://github.com/carpentries/training-template), click on the green "Use this template" button (top right)

   

3. Select the owner for your new repository. (This will probably be you, but may instead be an organization you belong to.)

4. Choose a name for your workshop website repository. This name should have the form YYYY-MM-DD-ttt-site, e.g., 2016-12-01-ttt-oomza, where YYYY-MM-DD is the start date of the workshop.   For online workshops, choose online as site. In most cases, the Instructor Training Team will tell you the name of the repository you should use.

5. Make sure the repository is public, leave "Include all branches" unchecked, and click on "Create repository from template". You will be redirected to your new copy of the workshop template respository.

6. Your new website will be rendered at https://your_username.github.io/YYYY-MM-DD-ttt-site.

Customizing Your Website

1. Go into your newly-created repository, which will be at https://github.com/your_username/YYYY-MM-DD-ttt-site. For example, if your username is gvwilson, the repository's URL will be https://github.com/gvwilson/2016-12-01-ttt-oomza.

2. Ensure you are on the gh-pages branch by clicking on the branch under the drop down in the menu bar (see the note below):

   

3. Edit the header of index.md to customize the list of instructors, workshop venue, etc. You can do this in the browser by clicking on it in the file view on GitHub and then selecting the pencil icon in the menu bar:

   

   Editing hints are embedded in index.md, and full instructions are in [the customization instructions][customization].

4. Alternatively, if you are already familiar with Git, you can clone the repository to your desktop, and edit index.md there, and push your changes back to the repository.

   git clone -b gh-pages https://github.com/your_username/YYYY-MM-DD-ttt-site
   

   You should specify -b gh-pages to checkout the gh-pages branch because the imported repository doesn't have a master branch.

   In order to view your changes once you are done editing, you must push to your GitHub repository:

   git push origin gh-pages
   

5. When you are done editing, go to the GitHub Pages URL for your workshop and preview your changes. In the example above, this is https://gvwilson.github.io/2016-12-01-ttt-oomza. The finished page should look something like this.

6. Optional: you can now change the README.md file in your website's repository, which contains these instructions, so that it contains a short description of your workshop and a link to the training website.

7. Optional: Add a link to your workshop website on the repository main page in the description/website section (look for the Edit button on the right to add).

Note: please do all of your work in your repository's gh-pages branch, since GitHub automatically publishes that as a website.

(Optional) Checking Your Changes Locally

If you want to preview your changes on your own machine before publishing them on GitHub, you can do so as described below.

1. Install the software described below. This may require some work, so feel free to preview by pushing to the website.

2. Run the command

   make serve
   

   and go to http://0.0.0.0:4000 to preview your site. You can also run this command by typing make serve (if you have Make installed).

3. Run the command

   make workshop-check
   

   to check for a few common errors in your workshop's home page. (You must have Python 3 installed to do this.)

(Optional) Linking to Your Page

At the top of your repository on GitHub you'll see

No description, website, or topics provided. — Edit

Click 'Edit' and add:

1. A very brief description of your workshop in the "Description" box (e.g., "Oomza University workshop, Dec. 2016")

2. The URL for your workshop in the "Website" box (e.g., https://gvwilson.github.io/2016-12-01-ttt-oomza)

This will help people find your website if they come to your repository's home page.

Creating Extra Pages

In rare cases, you may want to add extra pages to your workshop website. You can do this by putting either Markdown or HTML pages in the website's root directory and styling them according to the instructions give in the lesson template. If you do this, you must also edit _config.yml to set these three values:

1. carpentry is "cp" (for The Carpentries). This determines which logo is loaded.

2. title is the title of your workshop (typically the venue and date).

Note: carpentry and emailduplicate information that's inindex.md`, but there is no way to avoid this without requiring people to edit both files in the usual case where no extra pages are created.

Installing Software

If you want to set up Jekyll so that you can preview changes on your own machine before pushing them to GitHub, you must install the software described below. (Note: Julian Thilo has written instructions for installing Jekyll on Windows.)

1. Ruby. This is included with Linux and macOS; the simplest option on Windows is to use RubyInstaller. You can test your installation by running ruby --version. For more information, see the Ruby installation guidelines.

2. RubyGems (the package manager for Ruby). You can test your installation by running gem --version.

3. Jekyll. You can install this by running gem install jekyll.

You can check the formatting of your header by running bin/workshop_check.py (which is invoked by make workshop-check). You must have Python 3 installed in order to do this, and you will also need the PyYAML module.

Getting and Giving Help

We are committed to offering a pleasant setup experience for our learners, Trainers, Instructors and workshop hosts. If you find bugs in our instructions, or would like to suggest improvements, please file an issue or [mail us][email].

training-template's Issues

Use GitHub's new "repository templates" feature & adapt ReadMe

Just a pointer to this topic's main issue: carpentries/lesson-infrastructure#27 ;-)

Curriculum page no longer displays sample schedule

This template states: "Please see the Instructor Training Curriculum for course material and sample schedule for a 2-day event." However with the workbench there is not currently a sample schedule available in learner view.

I'm creating an issue because there's been some discussion about schedule displays and I'm not sure yet what's going to be changing. But whatever happens, the reference here should be accurate.

Fix incorrect URL examples

Related to incorrect URL in issue #21, the content under customizing your website has a mix of incorrrect URLs and no correct ones, which should be /YYYY-MM-DD-ttt-site. Super confusing.

Currently reads (with incorrect URLs bolded):

1. Go into your newly-created repository, which will be at https://github.com/your_username/YYYY-MM-DD-site-ttt. For example, if your username is gvwilson, the repository's URL will be https://github.com/gvwilson/2016-12-01-miskatonic-ttt.
   .
   .
2. Alternatively, if you are already familiar with Git, you can clone the repository to your desktop, edit index.html there, and push your changes back to the repository.

git clone -b gh-pages https://github.com/your_username/YYYY-MM-DD-site-ttt

4. When you are done editing, go to the GitHub Pages URL for your workshop and preview your changes. In the example above, this is https://gvwilson.github.io/2016-12-01-miskatonic.

broken link to lesson in workshop template

Link to "Starting with Data in Python" under the Preparation section is broken. Current link is http://datacarpentry.org/python-ecology-lesson/01-starting-with-data and should be http://datacarpentry.org/python-ecology-lesson/02-starting-with-data/.

Add survey links to template

Now that we have pre/post surveys for instructor trainees can we add them to this template (just like we have for the standard workshop template)?

Can we also have them append the workshop slug (again, like they do for the workshop template)?

Happy to do whatever is needed to make this happen but I'm not sure if there's more to it than adding a link in the template.

Update annual report link

To 2020 report :-)

https://carpentries.org/files/reports/Carpentries2020AnnualReport.pdf

Remove Zoom links?

This template currently prompts the user to add a direct Zoom link to the workshop. This should be updated to reflect the fact that connection information is delivered privately and need not be publicized here.

Update template to include 2019 Annual Report

We will be releasing the 2019 Annual report next week. Can we update the instructor training template to include that report in the reading list rather than the 2018 report?

Migrate this repo to https://github.com/carpentries/

This created issues at #7 (comment).

Update screenshot in README.md

The screenshot currently shows the wrong URL to import

Note that Etherpad is publicly accessible and linked to from the workshop website

We might want to add a note to the link to the Etherpad that it is publicly accessible. You only need the link and it is linked to from the workshop website. This should be made clear from the beginning, since trainees add their names, email addresses (though often institutional addresses), and personal opinions, stories and similar information to the Etherpad.

A similar note should be added to the top of the Etherpad template itself (where is the source for that?). Currently, there is a remark at the top that reads “Use of this service is restricted to members of The Carpentries community; this is not for general purpose use (for that, try etherpad.wikimedia.org).” The first sentence might be misunderstood to mean that no one else can access. Adding another item to the list of remarks could clarify that.

There might be more locations in the Carpentries documentation where this should be mentioned. For others, like the sign-up sheets for TD for example, it might not be necessary, since it is more obvious and the information provided is less personal.

Alphabetical listing of lesson programs

Our style guide says to list lesson programs alphabetically. The index page now has things listed in at least two different ways, neither of which is alphabetically 😄

The course is aimed at everyone who is interested in becoming a better teacher. In particular, this training is aimed at those who want to become Software Carpentry, Library Carpentry, and Data Carpentry Instructors, run workshops and contribute to The Carpentries training materials. You don't currently have to be an instructor or a teacher to attend this workshop, but you do need to be willing and committed to becoming one and to improving your teaching techniques.

Software Carpentry, Data Carpentry, and Library Carpentry's mission is to help scientists, researchers, and librarians get more research done in less time and with less pain by teaching them basic lab skills for scientific computing. This hands-on two-day workshop covers the basics of educational psychology and instructional design, and looks at how to use these ideas in both intensive workshops and regular classes.

Update recordign text for online workshops

Can we have help applying the logic that the workshop tempalte uses for online vs in person and then toggle off the "have somethign to take a recording" turned off for online workshops?

@fmichonneau or @zkamvar Can you help with this?

broken links

JordanPedersen/2023-02-21-ttt-online-EST#1 (comment)

(It seems like it should be possible to copy an issue from a fork, but this will have to do until I figure out how to do that!)

Website workflow run: build-website fails

On a generated repository the job build-website of the workflow Website always fails with error message:

Unable to resolve action `r-lib/actions@master`, unable to find version `master`

This happens already in the section Set up job, directly after Getting action download info, see log.

The website is correctly deployed via pages-build-deployment . Btw, what is the workflow Website used for?

Inconsistent links to pre- and post- instructor training surveys

Inconsistent links to pre- and post-instructor-training survey are being used (see https://gcapes.github.io/2019-10-08-ttt-manchester/ for example):

• pre-workshop survey link is https://www.surveymonkey.com/r/instructor_training_pre_survey?workshop_id=2019-10-08-ttt-manchester and points to the survey in Survey Monkey
• post-workshop link points to the page in instructor training material about surveys https://carpentries.github.io/instructor-training/06-feedback/#surveys where we do not have links to post instructor training surveys at all

Update to "Carpentries CoC"?

Can we change the wording to be "All participants are required to abide by the Carpentries' Code of Conduct"?

Make links to pre/post workshop surveys more prominent/findable

Brought up in the 2022-07-07 trainers meeting: the survey links are difficult to find on the websites and they should be more prominent.

Remove variable "title" from _config.yml or not use site.title in certain pages

See carpentries/workshop-template#513.

index.md instructions should indicate "ttt" as at least an option

and very likely the option

Conflicting schedules

The schedule in this template is not up-to-date with the schedule in the instructor training materials.

Compare: https://github.com/swcarpentry/training-template/blob/gh-pages/index.html#L226-L228
with the schedule here: https://swcarpentry.github.io/instructor-training/

I assume the latter should take precedence?

Link to IT curriculum Setup

Like we do for DC workshops and are discussing for SWC & LC workshops, we should rely on setup instructions that are in the lesson repo.

What's on the setup page now is different from what's on this repo's preparation section.

location/ accessibility options for online workshops

Given that many of these workshops are online, I think that an online workshop could benefit from a few changes to the workshop website, including, but not limited to:

• A header that says "Instructor Training" in bold rather than "online"
• Easy removal of the text about using google maps to find the location
• Removal of the accessibility descriptions, unless they are co-localizing

If other people agree that this would be a useful feature, I wonder if someone who knows how to write if statements can help make this a little more automated...

Add Library Carpentry links and references

• Library Carpentry is not mentioned on the landing page (aka the README.md file) here:
  https://github.com/swcarpentry/training-template
• There is no link to the Library Carpentry website on the about page (http://swcarpentry.github.io/instructor-training/about/) which I think is pulled from this html file (https://github.com/swcarpentry/training-template/blob/gh-pages/_includes/carpentries.html)

This helps fix https://github.com/ErinBecker/instructor-training-reorg/issues/37

Add Science of Learning to /files or use carpentries.org link

The index.md file contains the following relative link for the Science of Learning paper:
<li><a href="{{ site.training_site }}/papers/science-of-learning-2015.pdf">The Science of Learning</a></li>

The template doesn't include the paper in /files, so either the template needs to have the PDF added or (more likely) we need to change that to a hard link to https://carpentries.github.io/instructor-training/files/papers/science-of-learning-2015.pdf

Update template to use carpentries logo

instead of dc or swc logo

Some links in README that point to https://swcarpentry.github.io give 404

Some links with https://swcarpentry.github.io work as redirection to https://carpentries.github.io has been set (such as https://swcarpentry.github.io/lesson-example), other links such as for FAQ (https://swcarpentry.github.io/faq) and customisation (https://swcarpentry.github.io/workshop-template/customization/) do not.

default branch after import is not gh-pages

When you import this repository, the default branch is fix-18, not gh-pages. This is confusing when you import and merrily change the index file and then wonder why your website never updates. :(

I don't have access to the settings, so I can't fix this.