Home / Workflow / Instructional design review process

Instructional design review process : GitHub

Repository type: GitHub AzDevOps

This guide describes the general Instructional Design (ID) Review process for a typical project.

Note: The ID review process described in this guide is generalized and is not intended to capture the process entirely. The process can vary between projects and you should ask your project manager about the specific review processes that apply to the course you are working on.

Prerequisites

Before you proceed complete the following:

How an ID review is initiated

A content author initiates a review by sending an email to the reviewer to request an ID review. An ID review is usually requested when the author has completed content for a course module. The author’s email provides the following details:

GitHub username. The content author’s GitHub account username.
Module number The module number that the file(s) for review belong(s) to.
File name The name(s) of the file(s) to be reviewed.
Task type. The type of review required (i.e. ID review).

The file(s) for review should be on the master branch of the project’s GitHub (remote) repo.

Steps required to conduct an ID review

The following steps are required to conduct a general ID review as part of a typical project.

When you receive an email from a content author requesting a review, note the name(s) of the file(s) to be reviewed.
Use the Visual Studio Code (VSC) editor to clone the project’s GitHub repo onto your computer by following the guide Download course files (clone repo). The cloned repo you create on your computer is your local repo.
Create a new branch in your local repo with VSC using the guide Create new branch. The new branch is your local ID review branch, and should be created from the master branch in VSC.

Note: Apply the branch naming convention m <module number> idreview <id reviewer's surname> to your new branch, as described in ID review branch naming convention. For example, m6-idreview-lee.
In VSC, on your local ID review branch, open the first markdown file for review, and review the contents of the file according to WayPoint Ventures’ guidelines.
In VSC, apply, save, stage, and commit any necessary changes/ corrections you make to the markdown file by using the guide Send (push) files.
Push the file containing your changes to GitHub by following the guide Send (push) files.

Note: Push to GitHub regularly, e.g. after you have reviewed a lesson or single file. Do not wait until you have reviewed all of the files before pushing to GitHub.
In a web browser, access the project’s GitHub repo by following the guide View course files in web browser.
On GitHub, open a new Pull Request (PR) by using the guide Create pull request.

Note: Keep the new PR open (i.e. do not merge the PR yet). Keeping the PR open allows you to apply subsequent changes necessitated by the review process. Any further changes you make to the files on your ID review branch that you push to GitHub will be rolled into the open pull request. Configure the pull request by following the remaining steps in this guide.

General information about pull requests is available from the guide Pull requests overview.
On the GitHub page Open a pull request, use the dropdowns to configure the PR branches as follows:
- For base, choose the master branch.
- For compare, select the name of your ID review branch branch, e.g. m6-idreview-lee.
On the GitHub page Open a pull request, add the following into the PR title text entry field:
- number of the module the file you reviewed belongs to
- type of review you conducted (i.e. ID review)
- name of the base branch to merge into (i.e. master)
For example, a suitable PR title is: Mod 6 ID review merge into master
Optional: On the GitHub page Open a pull request, in the Write tab, add a checklist for each item to be reviewed by entering the following markdown syntax into the text entry field.
```
- [ ] ID Review Complete
    - [ ] ID Review Complete - Lesson 1
    - [ ] ID Review Issues Resolved - Lesson 1
    - [ ] ID Review Complete - Lesson 2
    - [ ] ID Review Issues Resolved - Lesson 2
    - [ ] ID Review Complete - Lesson 3
    - [ ] ID Review Issues Resolved - Lesson 3
    - [ ] ID Review Complete - Lesson 4
    - [ ] ID Review Issues Resolved - Lesson 4
    - [ ] ID Review Complete - Lab
    - [ ] ID Review Issues Resolved - Lab
```
Note: An item in your GitHub checklist can be a single topic, lesson or file (as appropriate). If necessary, consult the content author to determine a suitable approach to dividing the module content into GitHub checklist items.

Checklists provide a convenient way for ID reviewers, content authors, and other contributors to track the progress of an ID review. Checklists are optional; ID reviewers are not required to use checklists on GitHub.
From the right side menu of the GitHub page Open a pull request, in the Reviewers section, select the gear icon. In the text entry field, enter the content author’s GitHub username. Then, choose the author’s GitHub username from the list to add the author as a reviewer to the PR.

The following image shows adding the GitHub user eamonnk to the PR.

The following image shows the GitHub user eamonnk added as a reviewer to the PR.

Note: When you add a GitHub user as a reviewer to the PR (like a content author), GitHub will send the GitHub user a notification each time a change is made to the pull request (for example, when a file in the PR is edited or added).
On the GitHub page Open a pull request, choose Create pull request.
If necessary, consult the content author about the changes you made to the file on your ID review branch.
Note: Reviewers and authors can communicate in the following ways (among others) to discuss changes to content necessitated by a review:
- face-to-face meeting, video or voice call
- comments added to the Conversation tab on the GitHub pull requests page
- markdown comments inside a markdown file, formatted using the correct markdown syntax for comments described in the Markdown syntax guide
- email exchanges
On your ID review branch in VSC, open the next file for review and conduct an ID review of the file’s contents.
In VSC, apply any required changes/ corrections to the file on your local ID review branch. If necessary, apply any further changes/ corrections to the previous file in accordance with feedback from the content author.
On your ID review branch in VSC, save, stage, commit and push your changes to GitHub by using the guide Send (push) files.
Repeat Step 14 to 17 until all of the files for review have passed your ID review. Each time you push new changes, the author may evaluate your corrections and provide feedback.

Note: If you created a GitHub checklist, indicate when each item on the GitHub checklist has been addressed, and when the review has been completed, by using the checkboxes in the Conversation tab on the GitHub pull requests page.
When all content for review has passed ID review, in VSC, delete any comments from within the markdown files (do not delete comments from the pull request on GitHub).
On your ID review branch in VSC, save, stage, commit and push the passed files to GitHub (i.e. the files that contain your finalized changes).
On GitHub, go to the Pull requests tab for the (open) PR. Confirm that the this branch has no conflicts with the base branch message is shown. Choose Merge pull request to begin merging your ID review branch into master by following the guide Merge a pull request.

Note: If GitHub indicates that there are conflicts, follow the guide Resolve merge conflicts to address any outstanding merge issues, and then try merging the pull request again.
On the GitHub Pull requests tab, select Confirm merge to merge your ID review branch into master.
When the message Pull request successfully merged and closed indicates that the PR has merged, select Delete branch to delete your ID review branch by following the guide Delete branch.
Notify the copy editor by email (and the content author) that you have completed your ID review successfully.

ID review branch naming convention

Each reviewer must work in their own reviewer’s branch. A separate reviewer branch for each module is also required. This approach keeps the content separated per reviewer, at each stage in the process, and on a module by module basis.

Generally, a reviewer creates a reviewer’s branch from the master branch of the project’s GitHub repo using the guide Create new branch. When you create a new reviewer’s branch, your branch name should describe your branch’s content and make the branch’s purpose and owner clear to other contributors.

ID reviewers’ branches use the following naming convention (all lower case):

m <module number> idreview <reviewer's surname>:

The prefix m is for “module”.
<module number> refers to the module number that the file to be reviewed belongs to.
idreview is a short code for “instructional design review” i.e. the stage in the process the file is at.
The reviewer’s <surname> is added as a suffix to distinguish the reviewer’s work from other contributors.

Example ID reviewer’s branch name

The following explains how the example reviewer branch name m6-idreview-lee is constructed.

m is an abbreviation for “module”.
6 is the number of the module that the file(s) for review belong(s) to.
idreview is a short code for “instructional design review”.
lee is a reference to the reviewer’s surname.

Putting the previous items together results in the reviewer branch name m6-idreview-lee.

Key points about the ID review process

The following diagram provides an overview of key points in the general ID review process for a typical project.

Diagram of the instructional design review process

The following are key points about the ID review process.

Author requests ID review by email (when content for a module is ready).
ID reviewer:
- clone’s project’s GitHub repo
- creates local review branch from master in VSC
- reviews content in VSC on ID review branch
- applies, saves and commits necessary changes/ corrections in VSC (on ID review branch)
- pushes changes/ corrections to GitHub
- creates pull request (PR) to merge ID review branch into master
- adds author to PR as a reviewer on GitHub
Author evaluates pull request, and liaises with ID to provide feedback on ID reviewer’s changes
ID reviewer
- liaises with author to implement author’s feedback on ID reviewer’s changes
- completes ID review
- deletes comments from markdown files
- saves, stages, commits and pushes finalized ID review files to open PR
- merges ID review branch into GitHub master branch
- deletes the ID review branch
- notifies the copy editor when ID review is completed

Appendices

Check the following supplementary Appendices for more details and context.

⇠ Technical review process

Content editing process ⇢

Waypoint Ventures documentation