Merge pull request #20 from githubtraining/consistent-titles

Consistent titles

Author: hectorsector

config.yml

@@ -28,11 +28,17 @@ before:
     position: 6
   - type: updateBranchProtection
 
+# Repo artifacts:
+# 1. PR: Add a course title and description
+# 2. PR: Setup the learner's repo
+# 3. PR: Write the course steps
+# 4. Issue: Publish your course
+
 steps:
 
-# 2
+# 1
 - title: Give your course a title
-  description: Give your course a title
+  description: Name your course so learners can find it.
   event: pull_request.synchronize
   link: '{{ repoUrl }}/pull/1'
   actions:
@@ -73,9 +79,10 @@ steps:
       ```
     position: 8
 
-# 12
+# 2
 - title: Add some descriptions to your course
-  description: Add some descriptions to your course
+  description: Give your course a description and tagline so learners can identify it.
+  link: '{{ repoUrl }}/pull/1'
   event: pull_request.synchronize
   actions:
   - type: getFileContents
@@ -92,8 +99,10 @@ steps:
   - type: respond
     with: approve-first-pr.md
 
+# 3
 - title: Approve the course metadata
-  description: Approve the course metadata
+  description: Approve the pull request containing the course's metadata.
+  link: '{{ repoUrl }}/pull/1'
   event: pull_request_review.submitted
   actions:
   - type: gate
@@ -125,9 +134,10 @@ steps:
       ```
     position: 7
 
-# 3
+# 4
 - title: Point to the template repo
-  description: Point to the template repo
+  description: Designate a template repository from which to clone.
+  link: '{{ repoUrl }}/pull/2'
   event: pull_request.synchronize
   actions:
   - type: getFileContents
@@ -155,9 +165,10 @@ steps:
       ```
     position: 6
 
-# 4
+# 5
 - title: Give the learner's repo a name
-  description: Give the learner's repo a name
+  description: Designate a name for the repository when it is created for the learner.
+  link: '{{ repoUrl }}/pull/2'
   event: pull_request.synchronize
   actions:
   - type: getFileContents
@@ -174,8 +185,10 @@ steps:
   - type: respond
     with: approve-second-pr.md
 
+# 6
 - title: Approve the repo setup
-  description: Approve the repo setup
+  description: Approve the template repo information
+  link: '{{ repoUrl }}/pull/2'
   event: pull_request_review.submitted
   actions:
   - type: gate
@@ -231,9 +244,10 @@ steps:
       ```
     position: 9
 
-# 5
+# 7
 - title: Create an issue using Learning Lab
-  description: Create an issue using Learning Lab
+  description: Use the `before` block to create an issue in the learner's repo.
+  link: '{{ repoUrl }}/pull/3'
   event: pull_request.synchronize
   actions:
   - type: getFileContents
@@ -251,9 +265,10 @@ steps:
     data:
       fileUrl: '%payload.repository.html_url%/new/%payload.pull_request.head.ref%/responses?filename=responses/welcome-text.md'
 
-# 6
+# 8
 - title: Create your first response
-  description: Create your first response
+  description: Add content to the repo's first issue.
+  link: '{{ repoUrl }}/pull/3'
   event: pull_request.synchronize
   actions:
   - type: getTree
@@ -304,9 +319,10 @@ steps:
       ```
     position: 20
 
-# 7
+# 9
 - title: Name your first step and give it a description
-  description: Name your first step and give it a description
+  description: Identify the first step so the learner knows what's expected.
+  link: '{{ repoUrl }}/pull/3'
   event: pull_request.synchronize
   actions:
   - type: getFileContents
@@ -334,9 +350,10 @@ steps:
       ```
     position: 21
 
-# 8
+# 10
 - title: Trigger your first step with a GitHub event
-  description: Trigger your first step with a GitHub event
+  description: Add a pull_request.opened event.
+  link: '{{ repoUrl }}/pull/3'
   event: pull_request.synchronize
   actions:
   - type: getFileContents
@@ -364,9 +381,10 @@ steps:
       ```
     position: 32
 
-# 9
+# 11
 - title: Validate a learner's PR
-  description: Validate a learner's PR
+  description: Add a gate to determine if the learner took the expected action.
+  link: '{{ repoUrl }}/pull/3'
   event: pull_request.synchronize
   actions:
   - type: getFileContents
@@ -418,9 +436,10 @@ steps:
       ```
     position: 35
 
-# 10
+# 12
 - title: Use contextual information to validate
-  description: Use contextual information to validate
+  description: Add options to the gate action.
+  link: '{{ repoUrl }}/pull/3'
   event: pull_request.synchronize
   actions:
   - type: getFileContents
@@ -462,9 +481,10 @@ steps:
       ```
     position: 37
 
-# 11
+# 13
 - title: Respond to a learner's successful PR
-  description: Respond to a learner's successful PR
+  description: Use a respond action when a learner opens their pull request.
+  link: '{{ repoUrl }}/pull/3'
   event: pull_request.synchronize
   actions:
   - type: getFileContents
@@ -482,9 +502,10 @@ steps:
     data:
       fileUrl: '%payload.repository.html_url%/new/%payload.pull_request.head.ref%?filename=README.md'
 
-# 13
+# 14
 - title: Add a README to your course
-  description: Add a README to your course
+  description: Write a longform description for your course.
+  link: '{{ repoUrl }}/pull/3'
   event: pull_request.synchronize
   actions:
   - type: getTree
@@ -502,8 +523,10 @@ steps:
   - type: respond
     with: 13.0_publish.md
 
+# 15
 - title: Approve the steps
-  description: Approve the steps
+  description: Submit an approval for the steps pull request.
+  link: '{{ repoUrl }}/pull/3'
   event: pull_request_review.submitted
   actions:
   - type: gate

responses/01.0_add-title.md

@@ -1,6 +1,6 @@
 In the next couple of steps we'll [:book: Set up the course](https://github.github.com/learning-lab-equipment/#/3-4-yaml?id=set-up-the-course).
 
-## Step 2: Name your course
+## Step 1: Name your course
 
 Now, let's give your course a title.
 

responses/02.0_add-template.md

@@ -9,7 +9,7 @@ First, how will this content help teach the concept? For example, if a course is
 
 Second, is the finished product useful? At the end of the course, the finished repository should serve a purpose aside from the lessons. A working game, a portfolio or resume, or a collection of template documents are a few examples.
 
-## Step 3: Designate a template repository
+## Step 4: Designate a template repository
 Let's add our own template repository. To speed things up, we've created a template repository for you. We recommend using our template for this course.
 
 ### :keyboard: Activity: Add a template repository

responses/03.0_add-repo-name.md

@@ -1,6 +1,6 @@
 Awesome! Whenever a user registers for this course, Learning Lab will create a new repository for them based on `lab-starter-template`.
 
-## Step 4: Name the repository
+## Step 5: Name the repository
 
 `lab-starter-template` is a great template repository, and it's named to reflect that. But, we want the user to experience that repository through a _different_ name. We can designate that name in the `config.yml`.
 

responses/04.0_create-issue.md

@@ -6,7 +6,7 @@ Anything in this block occurs before the learner can access their course reposit
 ### Learning Lab actions
 Actions are reusable modules that each course has access to. They are each designed to do very specific things, and nothing more. This is to optimize for reusability and simplicity. The documentation contains a listing of [:book: all available actions](https://github.github.com/learning-lab-equipment/#/actions/).
 
-## Step 5: Add to the `before` block
+## Step 7: Add to the `before` block
 
 We'll use the [:book: `createIssue` action](https://github.github.com/learning-lab-equipment/#/actions/createIssue/) to create an issue for the learner with some initial instructions. The `createIssue` action requires two [:book: options](https://github.github.com/learning-lab-equipment/#/actions/createIssue/?id=options):
 - a title

responses/05.0_add-response.md

@@ -1,6 +1,6 @@
 Great! Now, the repository will have an issue for the learner.
 
-## Step 6: Creating a response
+## Step 9: Creating a response
 
 In the last step, we referenced a file titled `welcome-text.md`, but it doesn't exist. Learning Lab automatically looks in the [:book: `responses/` directory](https://github.github.com/learning-lab-equipment/#/3-5-responses) for all content files. Let's add it.
 

responses/06.0_add-first-step.md

@@ -12,7 +12,7 @@ For example, you _could_ write a lot of text and have the user close the issue w
 See [:book: best practices](https://github.github.com/learning-lab-equipment/#/3-5-responses?id=best-practices) in the Learning Lab docs for more suggestions.
 </details>
 
-## Step 7: Naming our first step
+## Step 9: Naming our first step
 
 Let's name our first step. We will give it a **title** and a **description**. These will be shown on Learning Lab, and they help course authors stay organized in the `config.yml` file. The docs show [:book: syntax and examples](https://github.github.com/learning-lab-equipment/#/3-4-yaml?id=relevant-syntax-1) of how steps are shown to the learner.
 

responses/07.0_add-trigger.md

@@ -3,7 +3,7 @@ Great! Your learner now has information about what they're expected to do in thi
 ### Events
 Every step in a course will be triggered by a GitHub Event. All possible events are documented in [Events Types & Payloads on the GitHub Developer Guide](https://developer.github.com/v3/activity/events/types/).
 
-## Step 8: Add an event
+## Step 10: Add an event
 Let's now find the `event` that will trigger the step. Because we want the learner to open a new Pull Request, the event we're looking for is [`pull_request`](https://developer.github.com/v3/activity/events/types/#pullrequestevent). Whenever this event occurs, information about the pull request is delivered to Learning Lab. However, if we just write `pull_request`, _any_ interaction with a pull request will cause this step to be triggered. We're specifically looking for the learner to _open a pull request_. We can filter the event to only opened pull requests by using `pull_request.opened` instead.
 
 ### :keyboard: Add an event

responses/08.0_validate.md

@@ -4,7 +4,7 @@ The events that can act as triggers help Learning Lab know when something happen
 
 Course authors can use **gates** to be validate the user's completion of a step. A [:book: `gate`](https://github.github.com/learning-lab-equipment/#/actions/gate/) is a Learning Lab action. Gates are conditionals, and they behave much like a conditional in Javascript. Let's add a `gate`, we'll specify its options in a later step.
 
-## Step 9: Add a gate
+## Step 11: Add a gate
 
 Let's now validate the learner's PR. We asked them to title the pull request "Add name to README" so that's what we need to validate against.
 

responses/09.0_add-context.md

@@ -1,4 +1,4 @@
-### Step 10: Add validation
+### Step 12: Add validation
 We need to validate against the learner's pull request title. This information is accessible to us [:book: from the payload](https://github.github.com/learning-lab-equipment/#/3-3-writing-steps?id=accessing-payload-data) that is sent with the event. In this case, the information was sent from a `pull_request.opened` event.
 
 You can see an example of all the information sent [in the GitHub Developer docs](https://developer.github.com/v3/activity/events/types/#webhook-payload-example-26).