# 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.

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

• 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.

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.

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