Learning Lab
Sign in

Best Practices for Responses

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.

Template 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._

General best practices

Contact information

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.

Voice

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.

Length of response

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.

Emoji

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:

  • Emoji shouldn't be used when writing error messages. Although a :+1: might appear to come with good intentions, a student might not infer that the bot is trying to be positive about their mistake.
  • Emoji can and should be used to convey tone, a :smile: or :grinning: emoji can show the postive tone of the bot's message
  • Emoji can be used to convey meaning, however, words should accompany said meaning. For example if identifying the user should approve a pull request, a :+1: emoji should be accompanied with explicit instructions to approve the pull request.

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.

Headers and activity syntax

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 activities

Introduction text

Readability

It probably goes without saying that if your text isn't easy to read, people are likely not to read it.

  • Write short, digestible paragraphs
  • Check for spelling and correct grammar,
  • Limit acronym usage (PRs, DVCS, etc.), follow with definition when using
  • Use markdown formatting to your advantage to help break up big blocks of text

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.

Images

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.

The details tag

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
image image

Syntax:

<details><summary>THE TITLE OF YOUR DROPDOWN GOES HERE</summary>

THE CONTENT OF YOUR DROPDOWN GOES HERE

</details>

Activity text

Reduce cognitive load with templates

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.

Short steps

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.

Suggested changes

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!!!

Next steps and warnings

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.

Structure

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:

  • Title
  • Descriptive paragraph text
  • Subparagraphs (optional)
  • Activities ⌨️
  • Next steps
  • Warnings (optional)

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.