While we keep to a similar structure, we also follow many other patterns that we've iterated on and explored to cultivate the best learning experience. You can find them below, sorted by section of response.
This template covers the main parts of a response structure, and might be a good place to start when writing responses. Keep in mind that the first post should have a header one (#
) but the subsequent posts should instead use a header two (##
). (This is covered in more detail below.)
# Title
This is the paragraph where I would describe the concept. I might link to other resources, or include images. I would try to avoid _too_ much information and _too_ many external links. The purpose of these paragraphs is to give the user the information they need to complete the activity, understand what they're doing, and understand why they're doing it.
### More detail
If there are concepts that should be described separatly, they might belong in a subparagraph section like this one.
## Step X: Description
Here, we'll describe generally what the user is about to do.
### :keyboard: Activity: Specific description
1. Step 1 in short sentence
2. Step 2 in short sentence
3. Step 3 in short sentence
<hr>
<h3 align="center">Watch below this comment for my response</h3>
> _Sometimes I respond too fast for the page to update! If you perform an expected action and don't see a response from me, wait a few seconds and refresh the page for your next steps._
As a course author, learners may want to contact you directly to report bugs or to ask questions. We recommend including a way for learners to contact you through a form or an email address in the first response.
From a content agnostic perspective, our learners are bright, inquisitive, and driven individuals. Our responses to their explorations in our courses should celebrate their successes and encouraging when they make a mistake. At no point should we trivialize the content they are exploring with terminology like "this is easy" or "a simple task" as this can be a deterrent to students who struggle with "easy" content and will be less likely to continue participating in the course.
Responses should be digestible amounts of information. Word count may range between 30 and 250 words per response, but we've found about 150 words per response is a good number.
As with most of our interactions with our in-person and online courses, emoji use is supported and encouraged. Refrain from using negative emojis like :-1: and :sad: when creating responses to mistakes or errors that the student might have made. Some additional information to consider when using emoji includes:
As an example of using emoji to convey meaning:
Use this:
> Another user submitted a pull request, visit the pull request and approve it :+1:.
Not this:
> Another user submitted a pull request, visit the pull request and :+1: it.
Inconsistent headers can create a confusing experience for the user, and they might struggle to determine how to prioritize your content.
Generally, we use the following conventions for headers:
#
for the very first header in your very first post##
for every first header following the first post###
for any additional sections### :keyboard: Activity:
before any activitiesIt probably goes without saying that if your text isn't easy to read, people are likely not to read it.
If you'd like help verifying how readable your responses are, try hemingwayapp.com.
There is a special balance between offering additional information and overwhelming the learner. Try to limit the number of external resources and links within responses. Favor the synopsis during the course, and provide other learning resources within the final post.
Augment text with relevant images. Choose images that add value, and are small enough in size but high enough in resolution to load quickly and clearly. This isn't necessary for all steps, but can be helpful to give learners a broader picture of new concepts.
Note: Use with caution!
Each course response should relate directly to the activity. In rare cases where you have more to say to the user that can't wait until the end to be an additional resource, you may want to display it in a more readable way. In this case, we recommend the details tag.
Before | After |
---|---|
![]() |
![]() |
Syntax:
<details><summary>THE TITLE OF YOUR DROPDOWN GOES HERE</summary>
THE CONTENT OF YOUR DROPDOWN GOES HERE
</details>
When asking the user to open an issue or pull request, it may be helpful to include a template in the repository or in the response. The goal is to help the learner focus on what you're teaching, not on the other steps that may get in the way.
Each activity will have a numbered list of steps for the user to complete. These should be short steps, usually under one sentence. In an activity where all steps are one sentence, do not include a period at the end. However, if at least one step is multiple sentences, then all steps should end in periods. We recommend trying to keep steps short so that all steps in a course are one sentence.
GitHub's Suggested changes feature can help you guide users through your course by having them click a button to accept your suggested changes instead of editing the file manually. This can help the user go quickly through a course by removing friction, but it also introduces a risk of becoming a point-and-click course. When using suggested changes, remember that every activity should be its own test. Are you testing if the user knows how to use suggested changes? Or, are you testing if the user can add the proper HTML tags?
Suggested changes can help - but use purposefully and with caution!!!
Sometimes, users can get lost trying to figure out what they should be doing next. We try to let them know what's expected so that they recognize if they're supposed to perform an action.
To do so, we use the following:
<hr>
<h3 align="center">Watch below for my response</h3>
Please note that once typing in HTML, regular Markdown rules don't apply. If you would like to add a URL to something in one of these tags, use <a href="link">
.
There are certain times where a user will have to refresh to receive their next set of instructions. We generally discover if this is the case during testing, and add the following to refreshable instructions:
> _Sometimes I respond too fast for the page to update! If you perform an expected action and don't see a response from me, wait a few seconds and refresh the page for your next steps._
or
> Turning on GitHub Pages creates a deployment of your repository. I may take up to a minute to respond as I await the deployment.
You'll notice that most responses in a GitHub Training course have a similar structure. These comments can be broken down into the following parts:
In keeping a consistent structure, we reduce cognitive load on the course participants. Users can focus on the response to find the exact information they're looking for.