Overview

Review 101

Video training content goes stale. egghead.io should be as up to date as possible when it comes to content. Because of the nature of video we need to monitor each lesson on multiple levels.


Lesson Video

An excellent coding screencast will focus on core concepts and have the ability to remain “evergreen” through minor revisions of the library that it is demonstrating. We need to continue to monitor this to make sure that it is the case.

When differences exist we can take several courses of action:

  • update the code sample and use comments in the code to notify the user that it has changed from the video
  • Annotate the lesson’s page to tell the student what is wrong with the lesson
  • Replace the lesson video/code with an updated version
  • mark the lesson as obsolete/deprecated
  • record a new version (vs replacement)

Update Lesson Code Sample

This is the most common action taken by the reviewer. The lesson code sample should reflect the current version(s) for the libraries it is demonstrating (libraries are updated often!). The sample code can correct for minor differences in the code demonstrated in the lesson video, noting with comments when this has been done.

Annotate the lesson page

When there is some significant breaking difference in the lesson video and code sample, we can create a notification to be displayed prominently on the lesson page. This notification comes in the form of an errata which is shown below:

Errata Example

Replace the lesson video/code

If the lesson still has significant value conceptually, we can re-record the lesson and produce an updated code sample. We want to do this for popular lessons and maintain our SEO.

Make a note of why you think the lesson needs to be re-recorded in the review document.

Mark as obsolete

Like Annotation above, but more deadly! :skull:

Record a new lesson

Sometimes we will want to record a new lesson that presents the underlying concept with the updated version instead of replacing it in-place

Setup

There are a few essentials needed on your computer in order to review. In this section you are going to follow along and install everything that is needed.

Quick Install (Mac)

Open up your terminal paste in the following and then press return to install Homebrew: /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Afterwards you're going to run each of the following in your terminal:

  • Google Chrome: brew cask google-chrome
  • Slack: brew cask install slack
  • GitKraken: brew cask install gitkraken
  • Visual Studio Code: brew cask install visual-studio-code
  • Yarn: brew install yarn

Google Chrome Plugins

React Developer Tools

The React Developer Tools extension is needed for reviewing our React course content. You can install it here: React Developer Tools

Video Speed Controller

Video Speed Controller allows you to quickly adjust the video speed with your keyboard. Install it here: Video Speed Controller

VS Code Extensions

Extensions enable VSCode to be more helpful, providing more visual feedback or shortcuts that prevent you from having to type more than necissary.

You can install these extensions by running the provided scripts from your terminal.

Markdown All in One

Markdown All in One provides you with shortcuts and a preview of your markdown.

Install script: code —-install-extension yzhang.markdown-all-in-one

ESLint

ESLint warns you if you are breaking any rules inside your editor, letting you know if you've made a mistake early.

Install script: code —-install-extension dbaeumer.vscode-eslint

Prettier

Prettier formats your code when you save a file, ensuring that all outputted code conforms to a consistent style.

Install script: code —-install-extension esbenp.prettier-vscode

Quokka.js

Quokka.js is a rapid prototyping playground for JavaScript and TypeScript. It runs your code immediately as you type and displays various execution results in your code editor.

Install script: code —-install-extension wallabyjs.quokka-vscode

Github Pull Requests

This lets you view and create pull requests inside the editor!

Install script: code —-install-extension github.vscode-pull-request-github

Accounts

Github

Your Github account is what you'll use to create accounts with all the other required services.

Sign up here 👉 github.com

Once you have an account created contact a Content Team Lead and they will provide you with the invitations to egghead.io's Github organizations.

Required Learning

Communication and Work Structure

Overview

There are quite a few tools that we use at egghead that allow us to communicate, organize, and plan our thoughts and work. This section will explain how we use each tool and give you an understanding of why we use it.

After reading this section, you'll know how we communicate as a team at egghead and where work is done.

We'll cover:

  • Github
  • Slack
  • Email
  • Topic Box

GitHub

GitHub is a website and service used to store and track the development of software. It does this through Git which the tool that actually keeps track and manages code.

GitHub is a hosting service for projects (repositories) that use Git. It's not the only service that does this but is widely accepted, especially in Web Development.

For more specifics on Git, visit our Prerequisite section [link to that].

GitHub & the Review Team

GitHub is where we store code examples for the content that is created at egghead. Specifically, all code is stored under the eggheadio-projects organization.

Each repository (with a few exceptions) in this organization will correlate to a course that has been or will be published on egghead.

Github Projects

Work is assigned through GitHub Projects which can be found here.

You can navigate to the project from the organization home page here:

screenshot of github projects button

Then select Review Team Projects

This will bring you to all the current reviews that are currently being worked on as well as available for review.

screenshot of github projects button

On this board we have 4 columns: Todo, Working On, Needs Review, and Dependency Data Merged.

When a course is flagged for review, it will be added to the Todo column as an issue by a Review Team Admin. When you are ready for a new project, you can assign yourself to the issue and drag the issue to the Working On Column.

When a review is done, you will need to move the related issue to the Needs Review column for review by a Review Team Admin. In addition you'll need to post to Slack (covered in next section).

When the review is approved, the issue will be closed and moved to the Dependency Data Merged column.

Review Project Issue

screenshot of github projects with issue open

This will take you to the full issue page that will describe for you what needs to be done and give appropriate links for you to start the project.

screenshot of github projects button

Each card will have the lesson minutes and pay at the top of the card as well as quick references for Setup, The Review, Finished, and Copying the JSON (We'll cover more specifics in the review section).

In addition, more context will be added to the top of the card when available. Notes on previous pain points in past reviews, comments from customers, relevant changelog notes of a specific technology, etc.

Asynchronous Communication

Because team members are spread across the globe, our primary form of communication is asynchronous. We use Slack as the day to day tool for questions that need to be answered immediately as well as a place to post work, ask for reviews

  • email

Review 101

Review 101

Video training content goes stale. egghead.io should be as up to date as possible when it comes to content. Because of the nature of video we need to monitor each lesson on multiple levels.


Lesson Video

An excellent coding screencast will focus on core concepts and have the ability to remain “evergreen” through minor revisions of the library that it is demonstrating. We need to continue to monitor this to make sure that it is the case.

When differences exist we can take several courses of action:

  • update the code sample and use comments in the code to notify the user that it has changed from the video
  • Annotate the lesson’s page to tell the student what is wrong with the lesson
  • Replace the lesson video/code with an updated version
  • mark the lesson as obsolete/deprecated
  • record a new version (vs replacement)

Update Lesson Code Sample

This is the most common action taken by the reviewer. The lesson code sample should reflect the current version(s) for the libraries it is demonstrating (libraries are updated often!). The sample code can correct for minor differences in the code demonstrated in the lesson video, noting with comments when this has been done.

Annotate the lesson page

When there is some significant breaking difference in the lesson video and code sample, we can create a notification to be displayed prominently on the lesson page. This notification comes in the form of an errata which is shown below:

Errata Example

Replace the lesson video/code

If the lesson still has significant value conceptually, we can re-record the lesson and produce an updated code sample. We want to do this for popular lessons and maintain our SEO.

Make a note of why you think the lesson needs to be re-recorded in the review document.

Mark as obsolete

Like Annotation above, but more deadly! :skull:

Record a new lesson

Sometimes we will want to record a new lesson that presents the underlying concept with the updated version instead of replacing it in-place

The Review Process

Identify Change(s) in a Framework

Project Structure

JavaScript frameworks are continually changing and updating. A lot of the time this is not an issue for our lessons.

JavaSript projects keep track of changes through a package.json that can be found in the root of the project. The package.json file contains the meta-data for the project like the authors' name, a scripts section, dependencies section, and devDependencies section.

The dependencies section contains the list of all the libraries used in the project that are essential for the application to run (e.g., React, Angular, Redux, RxJS).

{
  "name": "redux-course",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "json-server": "^0.13.0",
    "react": "^16.4.0",
    "react-dom": "^16.4.0",
    "react-redux": "^5.0.5",
    "react-router-dom": "^4.1.1",
    "redux": "^4.0.0",
    "redux-devtools-extension": "^2.13.2",
    "redux-thunk": "^2.2.0",
    "yarn": "^1.6.0"
  },
  "devDependencies": {
    "react-scripts": "1.1.4"
  },
  "scripts": {
    "start": "react-scripts start",
    "production": "json-server --static ./build db.json",
    "build": "react-scripts build",
    "test": "react-scripts test --env=jsdom",
    "eject": "react-scripts eject",
    "dev-server": "json-server -p 8080 db.json"
  }
}

Each of these dependencies has a version number listed that informs npm (or Yarn) to download the version specified.

The version number follows the Semantic Versioning Specification (SemVer).

Semantic Versioning (SemVer)

SemVer attempts to provide more meaning of the underlying changes in a project through additional structure to version numbers.

Each Version X.Y.Z must be non-negative numbers starting and (supposed to) have non-leading zeroes (though many libraries start at 0.1.0).

  • X is a MAJOR version

  • Y is a MINOR version

  • Z is a PATCH version

With these versions specified, 0.2.10 is ordered before 0.3.1 and subsequently, 1.0.0 comes after both 0.2.10 and 0.3.1.

A PATCH version is incremented when internal bugs are fixed in a library that does not affect any projects. MINOR versions are incremented when there is 'backward compatible' features introduced to a library or significant improvements to the internal workings of the library are added. MAJOR versions are incremented when there are Breaking Changes introduced to the library.

In the previously mentioned example, theoretically, there are backward compatible features added in-between the packages 0.2.10 and 0.3.1 versions. When the package reached 1.0.0, it can be assumed that it contains breaking changes if you wrote your application on a previous version (e.g., 0.2.10 or 0.3.1).

SemVer Version Ranges

A lot of the time, specifying a single version of a technology is too fine grain and restrictive because subsequent MINOR and PATCH updates won't break the project that the dependency is in. It can be annoying to have to update version numbers every time a MINOR or PATCH version is released.

This is why SemVer has version ranges which can be denoted a few different ways. The simplest ways are to use a set of primitive operators, which are: < Less than, <= Less than or equal to, > Greater than, >= Greater than or equal to, and = Equal. = can be assumed when no operator is present.

For review, a range specifying >15.3.0 <16.4.1 says the course started at version 15.3.0 and is valid up to all version (excluding) 16.4.1 where a <=16.4.1 will specify the version including 16.4.1.

Simply putting 15 - 16 is another way to specify a range that will encompass all MINOR and PATCH versions contained within the MAJOR versions 15 and 16. This is preferred as it is the most flexible way to specify a version range. If more specifics are required, other operators can be used.

To make versions easier to specify, the squiggly ~ and caret ^ also identify ranges. When ~ is placed before version (e.g., ~15.0.0), it specifies all versions incremented at the PATCH level. In other words 15.0.1, 15.0.3, or 15.0.19 are all valid. In other words, ~15.0.0 equals >=15.0.0 <15.1.0.

The caret ^ specifies all version increments at the MINOR and PATCH levels. ^15.0.0 specifies that any of these following versions are valid: 15.0.1, 15.1.3, or 15.5.0. in other words, ^15.0.0 would equal the range >=15.0.0 <16.0.0.

A great place to explore semantic versioning is the npm SemVer calculator

Pre-release Versions

Many projects will have several pre-release versions published before an official version is published. These pre-release versions are subject to change and can be typically ignored when updating lesson code.

Pre-release tags range from alpha, beta, and rc (release candidate). With the specified order as follows: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0.

It is good to note that a pre-release is available and what stage they are in as that likely means a MAJOR version update is close to being published and will trigger more reviews.

Review with SemVer Versions in Mind

You need to identify these Breaking Changes​​​​​​​ and keep them in mind when watching through lessons.

Each framework or library will have a CHANGELOG.md that will record the changes of that specific framework. (link to example) Usually found on the respective frameworks github page.

Most frameworks use Semantic Versioning (SemVer) to keep track of updates. We are mostly interested in Major and Minor

Under each new version, there will be a Breaking Changes (or similarly named) section that is where you will see what exactly will break any lesson examples that egghead might have.

Track Course Dependency Information

egghead is now keeping track of all the relevant dependency versions related to a course

i.e., A course on "State Management with Mobx in React" will track the version range that starts with the course published version and ends with the current version the course example.

Data for this looks like:

{
        slug: 'manage-complex-state-in-react-apps-with-mobx',
        dependencies: {
          mobx: '2 - 5',
          react: '15 - 16',
        },
        reviews: [
          {
            performedOn: '2018-07-17',
            performedBy: 248653,
            scopeOfReview: 'full course lesson review',
            notes: [
              {
                type: 'major issue',
                title: 'removed line- “useStrict(true);',
                details: 'The useStrict terminology is no longer recognized',
              },
              {
                type: 'major issue',
                title: 'Keys and values now return iterators',
                details:
                  'keys and values now return iterators, to return an array, use Array.from with the iterator https://github.com/mobxjs/mobx/issues/1488',
              },
            ],
          },
        ],
      },

As seen above, every review is recorded with the date it was done (in YYYY-MM-DD format), the scope, and most importantly, any notes or issues that came up during the review.

The range specifies the range that starts with package versions that the course was released on and ends with the latest version the course was updated to. For the example specified above, the course was released with React v15 and has since been updated to React v16. The specific MINOR and PATCH versions aren't necessary to specify here because there are no major breaking changes of concern apart from the notes provided.

Title a egghead.io lesson

[How Do I…] Standard

The title of the video needs to reflect the question that is answered in the video. Finishing the How do I… question is a great way to accomplish this and is the standard for our lessons.

This is a standard that we have adopted recently so many of our older lessons and courses do not have this standard applied and need to be updated accordingly.

Another way to think about the title of a video is that it is the summary of the description (of the video). If the summary answers the question the title proposes, you are on the right track.

90 character limit

Search Engine Optimization (SEO)

Our titles are also one of the main resources we use for exposing our content to the internet. We want to include the technology that the lesson is covering in the title.

Here's a list of lesson title examples and how we updated the titles to our new standard.

Old Title

  • Filters
  • Observables are almost like Functions
  • Creation operator: of()
  • Understand Elm’s Bool Type

Updated Title

  • Filter Input in AngularJS
  • Return Multiple Values with Observables in RxJS
  • Deliver Synchronous Values with the RxJS of() Operator
  • Pattern Match Expressions with Elm’s Boolean Type

Your course code example

A course typically has one code example that acts as a connecting thread through the course. You’ll build on it from lesson to lesson.

For every egghead lesson, we provide a concise, organized, readable code example below the lesson video in a runnable embed, using CodeSandbox or a similar service. That way, egghead members can jump in right away.

The structure that has worked best is to place each lesson example in it's own folder on the master branch numbered acording to the lesson order in the course. This allows for quick access to each lesson without the hassle of switching branches (this is important for further maintanence!).

Here's an example of the structure that we expect:

screenshot of code example on github

Each folder contains a create-react-app application that's ready to run.

screenshot of specific folder of code example on github

How Code is Shared

For each lesson in a course, a code example is provided in its finished state below the video so learners can explore the code on their own.

CodeSandbox is our favorite tool for creating and delivering our examples. If this won’t work for the code, we use a GitHub repository to store the code example and share that on the lesson page. GitHub repo examples will be structured in the same way, where each folder is the finished state of the given lesson.

Poviding a app.start.js file (or folder if a few files in one lesson are touched) is a great way to encourage students to code the lesson themselves.

Enhnacements to the Code Example

To further the useability of each repository, egghead will implement Yarn Workspaces which allow anyone to yarn install once for the entire repository and each lesson will be ready to run. No more hassle for the student to install in every lesson folder.

This is opt in for each student as she can still navigate to the lesson folder and npm or yarn install, but for maintanence purposes, workspaces greatly increase the speed of updating and ensuring every lesson is running as it should.

Two additional requirements for each lesson folder are a unique name in it's respective package.json file as well as version set.

As seen here in this example:

screenshot of lessons package.json

Next, all lesson folders (or workspaces) are aggregated in a packages folder and a global package.json file is created to enable the workspaces.

screenshot of lessons package.json

Within that package.json file, you'll set workspaces to packages/* and private to true. Now you're all set up with what you need to run each example as a workspace.

You'll notice that we've added a few handy scripts in this global package.json that allow you to easily run and update each lesson.

yarn start 01

💥 The first lesson is ran.

Review Template

Review Author:
Date of Review:
Transcripts Enhanced? (Y / N):
Link to Course:
Course Notes:
Breaking Changes Between Video and Latest Version:
Ideas for Potential Lessons:

Lesson Title → Updated Title

 Notes:
 Summary:
 Updated Description:
 Link to Plunker:
 Changes Made in Code:

The Code Part

  1. What to ask
  2. Debugging
    1. know when to stop and ask for help
  3. Updating
  4. Migration
    1. Services (codesandbox, local server, plunkr, etc.)
    2. Changing a project's structure

Getting Paid

  1. introduction with deborah
  2. routing number
  3. account number
  4. Wave? - creates invoices, receipts