Skip to content

Exercise Standards

Description and Purpose

An exercise is the level of the LE that a learner interacts with when completing a Lesson. It typically accomplishes one or more learning objectives through direct instruction (narrative) and checks for understanding (checkpoints).

Content Location

An exercise is contained within a lesson. An exercise itself contains a narrative and at least one LE component (code editor, terminal, output terminal, image, or video). Most exercises are interactive and include checkpoints or instructions.

An exercise broken up into 3 columns contains the narrative and checkpoints/instructions in the left column, a workspace in the middle column, and other components in the right column

Overarching Standards

Fields in Author

Content

Narrative

A narrative is the LE content that provides an introduction to new material. It is shown in the left third of the LE.

  • Narratives should include key terms (conceptual and syntax) and their definitions according to the Learning Standards associated with the lesson.
  • Narratives should provide examples, analogies, metaphors, or stories to aid understanding of new concepts
  • For practical exercises, narratives should include code examples to demonstrate syntax or coding concepts. Code examples should be followed by an explanation.
  • For conceptual exercises, narratives may include diagrams, static images, or GIFs to explain concepts and/or key terms. Diagrams should be followed by an explanation.
  • The narrative in the first exercise should have a "hook" that engages learners in the lesson content.
  • The narrative in the first exercise should provide an overview of what the lesson will cover.
  • The narrative in the last exercise should summarize material introduced throughout the lesson.
  • When possible, narratives should reinforce and build on concepts introduced in previous exercises.
  • Narratives may include hyperlinks to additional resources. Some reasons to use hyperlinks: internal links to other Codecademy content, official documentation or definitions (Wikipedia), for citation purposes.
  • ​​When possible, the narrative length should be shorter than 250 words. Strive for concision!

The "Use Instructions Instead of Checkpoints" Toggle

When turned on, the Checkpoints field will be replaced by Instructions.

  • Instructions should be used when there is an open-ended or non-testable interaction.
  • Instructions should direct learners to interact with the LE component provided, such as analyze a diagram, perform an action off-platform, engage with a provided web browser, etc.
  • With instructions learners will be able to move on to the next exercise without needing to pass any tests.
  • Only one instruction is supported and there is no "hint".
  • See Checkpoints Instructions (below) for further guidance on writing instructions.

Checkpoints

Checkpoints provide instructions to learners and evaluate learner code with tests. Checkpoints are contained within exercises.

  • Exercises may have zero or more checkpoints.
  • Each checkpoint accomplishes one task. The scope of a "task" may vary depending on the complexity of the learning objectives of the lesson. For example, in an early exercise covering declaring variables, a single task would be declaring a variable and assigning it a value. In a later exercise on implementing an algorithm, the learner may be asked to declare multiple variables or call multiple functions in one task.
Checkpoint Instructions

Checkpoint instructions describe the tasks the learner needs to complete.

  • Instructions may include text, markdown, inline code, code blocks, HTML elements.
  • Instructions should provide the rationale for the task the learner is being asked to accomplish.
    • For example, the following instruction provides rationale, "Now let's practice how .pop() removes an element. Call .pop() on groceryList to remove the last element.""
    • Whereas pure instructions would be: "Call .pop() on groceryList."
  • Instructions should not provide the exact solution code.
Checkpoint Test

For writing tests, see the Test Standards.

  • If the learner gets the final savepoint, each checkpoint test within the exercise should pass (if possible).
Hint

Checkpoints hints are provided when necessary to guide learners to the correct answer. Hints are hidden by default and require learners to reveal them.

  • Hints shouldn't provide exact solution code. Rather, hints should provide an example of the syntax used to pass the checkpoint.
  • Do not introduce new material or syntax in the hint.
Checkpoint Notes

Checkpoint notes are for internal purposes and will not be displayed to learners. They are optional.

Layout Components

Learning Environment components are interactive elements that typically replicate a real-world tool, such as a Code Editor, and allow learners to take specific actions in the exercise.

  • Each exercise should have at least one LE component.
  • Depending on which components are used in an exercise, different tests and checkpoint functionality may be available. For each type of component, refer to the component's specific standards page.

Workspace

See Exercise Workspace Standards

  • The workspace field does not need to be filled out for Image or Video layout components.

Startup Command

Sometimes it's necessary to get an exercise into a specific state when it loads the first time. This is where a startup command might come in handy. Here's an example of a command used for a Ruby-on-Rails exercise.

A startup command can be added in the Workspace section of an exercise in Author

Run Once: A startup command will only run once, either during first visit to an exercise or when exercise is “reset” to the initial savepoint. If you need to start a service every time a learner loads an exercise, talk to the Learning Platform team — a startup command is not the right fit for this.

Note: If you are editing an exercise and “Preview” it, the startup command will only run the first time an exercise is previewed. You must reset the exercise for a startup command to run again.

Single Command: A startup command is interpreted as a single string in a given exercise, which means that the shell will only recognize a single command. However, there are two workarounds to run multiple commands:

  1. Chain commands together within the startup command section (e.g., mkdir bloop && touch bleep.py).
  2. Add commands into a file in the workspace (e.g., setup.sh). The startup command can then run that file (e.g., bash setup.sh).

Separate Process: A startup command is run in its own separate shell process. Neither the command nor output will show up in the learner's terminal.

Contained to the Workspace: Startup commands are ideal for making changes that persist on the file system, but only within /home/ccuser/workspace/your-workspace-slug/. File changes above that directory will not persist between sessions.

For example, making changes to the bash profile ~/.bashrc a.k.a. home/ccuser/.bashrc will not persist between sessions.

Attributes

Title

The title of the exercise, displayed to learners at the top of the narrative in the LE and in the course menu.

  • Titles should include key terms when appropriate (for SEO purposes).

Slug

The slug is used to create a URL for the content item.

  • The slug is auto-generated based on the Title field though it can be edited.

Linked Content

Containers That Use This Exercises Lesson

This field is auto-generated and will populate any containers that contain this exercise.

Examples

Here are several examples of entire exercises:

Here are several examples of great checkpoints:

Here are several examples of excellent hints: - Iterating through Strings - gives the structure of the code without letting the learner copy and paste - Feature Testing - describes the arguments expected to be passed to a given function