Planning your course

GitHub Learning Lab is no longer accepting new public courses from outside of GitHub.

Striking the right balance in a course's length, complexity, and practicality is important. You're engineering an experience, not just creating a course. The following tips should help you design a great learning experience.

1. Vet your course ideas

Learning Lab is designed to help people learn how to develop great software. If you need help deciding whether your course or project will do well on Learning Lab, this resource will help.

2. Create course goals

Take a few minutes to create some goals for your course. Jotting down answers to these questions is a good start:

What will learners be able to do after completing your course?
What experience should a learner have before starting?
What can they do to continue to evolve the project after they've completed the course?

3. Create a course outline

Using the course goals, create a list of logically ordered tasks the learner will complete. It should look something like this:

Create the index.html file
Add essential tags <html>, <head>, <body>
Add "Hello world" text
Deploy to GitHub Pages
Experiment with formatting of "Hello world" text

4. Connect tasks with GitHub Events

GitHub Learning Lab listens for events that happen on GitHub and then responds to those events. Connect each task with the event you would expect to see on GitHub and the data you would be looking for in the event payload:

Task	GitHub Event
Create the index.html file	Creating the file will create a push event but you can also use the pull request event - you'll decide which one to use in the next step
Add essential tags `<html>`, `<head>`, `<body>`	This will create a push event
Add "Hello world" text	Another push event
Deploy to GitHub Pages	This will create a page_build event
Experiment with formatting of "Hello world" text	More push events

5. Connect events with Learning Lab actions

Learning Lab responds to the events generated by the learner using Learning Lab actions. It helps to begin thinking about these actions during the planning process. Using the example above:

In the first step, we'll ask the user to create an index.html file and open a pull request
The event payload for the PullRequestEvent gives us the url for the most recent commit
We'd use the Learning Lab action getTree to take a look at the commit
Then we'd use the Learning Lab gate action to see if that commit contains a file named index.html
If it does, we could use the respond or create review action to comment with the next step.
If it doesn't you can use the respond or create review action to provide instructions on how to create or rename the file.

Depending on what you expect from the learner, you can do multiple checks on the same event. For example, you can see if they included an @ mention in their pull request comment, created the pull request against the default branch, and added specific text to the file. Just remember to write helpful responses for each check so the learner will know what they need to fix.

6. Create the course flow

Now that you have an outline, it's time to think about the end-to-end interaction with the learner. We break this in to 3 categories:

Before: what should the bot do in the course repository before the learner arrives? What setting should be enabled? What should the welcome comment say? What is the first thing the learner needs to do?
Steps: this is the majority of your course. Once the learner enters the course, the bot will be waiting for the learner to do something. You defined this in the before step, so step 1 will begin when an event is received from the learner's GitHub repository and end when the instructions for step 2 are posted.
Final step: When the learner reaches the final step in the course, the bot should comment one last time with a "congratulations" message and recommendations for further learning.

Resources

If you'd like to view samples of completed courses, check out our open source courses. Go to the GitHub Training organization and select the learning-lab topic.