# Katacoda Formatting and Design Guide

# What is a Scenario, Anyway?

Scenarios are interactive lessons using the tools modern developers use as they build new products. Scenarios should:

  • Cover one specific learning objective or problem. This could be:
  • a lesson
  • an exercise, such as implementing something new, changing something that exists to work differently, or troubleshooting an example that is broken (on purpose!) in order to fix it
  • a fix for a common coding issue
  • a cookbook-style recipe
  • Look at this one, which shows a great example of a context-setting landing page, clear objectives, and accomplishes what it sets out to teach in only 10 minutes.

  • Take no more than 5-15 minutes for the learner to complete

  • Take the form of a contextualized “story” (loosely defined) that establishes both situational and emotional relevance.

  • Situational relevance establishes how and why I need to learn this.
  • Emotional relevance aids in the creation of new memories, so learners are more likely to remember what they've learned. The easiest way to trigger emotions is to frame the scenario as a story. Even a hypothetical, contrived story helps people learn and remember.

For example, in the Get Started with Hashcat scenario, the tone is conversational, and uses phrases like "Let's pretend for a moment..." and "your initial reaction might be something along the lines of 'That was frighteningly easy!'".

These techniques place the learner into the narrative as they learn.

Titles should be provided in the following format when possible:

Kubernetes: Launch a Single-Node Cluster

The scenario title should:

  • be brief
  • include the primary technology addressed (noun)
  • summarize the task or activity involved (verb + object)

# Learning Experience Approach

What is unique about Katacoda Scenarios? How do people learn from scenarios (as opposed to books, workshops, or any other mode), and how should this inform how you author yours?

This format helps people learn by:

  • Encouraging forward momentum by eliminating setup needs and providing a ready-made working environment, thereby also eliminating many potential stumbling blocks. (There's less that can go wrong!)
  • Providing clear paths forward. The lesson text is used to introduce new concepts, but must also always provide a clear next step. “Type this.” “Click this button.” “Call this function.” Learners should never be confused about what to do; always point to what's next. Katacoda usually copies text into the editor or shell automatically, but learners should always understand what to do next if they were working outside the scenario.
  • Encouraging safe, worry-free experimentation. People learn best when they can tinker or tweak a system to learn how it works. Working in a sandbox environment reduces anxiety, especially for beginners, who worry “Am I doing this right?” and “Will I break something if I try this?” In the sandbox, you can't “break” anything.
  • Supporting different levels of engagement. You can skim a book, or explore it slowly and deeply, pursuing each of the exercises it describes. Similarly, with a Katacoda scenario, the principles above combine to support different levels of learner engagement: Someone should be able to progress quickly through a scenario (click next, next, next, next, done) and be able to stop at any point, tinker, and explore. Both use cases are valid (and valuable) modes of learning.

As such, you should design your scenario for “no typing required.” As a practical matter, authors should always encode clickable coding shortcuts. Ideally, every scenario can be completed successfully without any typing at all — only clicking the “next” buttons and the embedded shortcuts.

This “no typing required” rule supports both learning modes. Those who want to click through quickly can do so. And those who want to type in commands manually or otherwise take more time can.

Note that motivations for moving quickly can vary. Some use cases:

  • An expert with preexisting foundational knowledge.
  • A novice, revisiting a scenario they've already seen, “jumping ahead” before spending more time within a specific part of the scenario.
  • Any learner, skimming the content to evaluate its appropriateness for their needs, before then starting the scenario over and reviewing it more slowly.
  • The author of the scenario (you!) is verifying the content.

# It’s Time for a Rough Sketch

Before you get building, you should have at least a rough sketch of each of the steps you’ll cover in your scenario. Think of this as a storyboard.

  1. Think of the goal.
  2. Identify key steps the learner needs to take to get there.
  3. Decide how much detail you want to include.
  4. Write a description of what each step will cover.

Keep it ROUGH. Keep it MOVING. Consider CONTINUITY. Watch out for jumps in LOGIC.

# Creating a Consistent and User-Friendly Authoring Style

Below, you’ll find a list of recommendations and best practices for making great scenarios:

  • Keep titles and descriptions succinct.
  • Include an Intro - Set the stage and let learners know what to expect
  • Include a "Lessons Learned" page at the end to summarize what the learners should have picked up
  • Give credit where credit is due - did you use an image or idea from someone else? Let the learners know.
  • Add complicated software set-ups to the image itself - avoid asking users to install software after they launch
  • Aim to keep your Kubernetes and Ubuntu scenarios running at or under 4CPUs and 4GB of Memory
  • Keep your instructions simple to avoid taking up precious space. For example, we recommend:

Take a look at the YAML files that define this application.

cat echoserver.yaml

instead of

In the next step you will see there is a YAML file that defines this application. Click on or type this command to see the YAML file.

cat echoserver.yaml