Link Search Menu Expand Document

Tips for Challenges

Writing quality challenges that your learners appreciate can be challenging (pun intended). Challenges often require a different writing style from the more straightforward tutorial models in standard labs. Challenges ask more from you as an author such as:

  • Precisely worded tasks
  • Verification scripts that are contextually aware
  • Tracking learner progress
  • Anticipating learners deviating from happy-path
  • Contextually sensitive hints that guide and teach without fully revealing the whole solution
  • Solution instructions to help test and produce as you develop and maintain the challenge
  • Manual and automated testing

Before publishing your challenge, consider this quality must-have checklist:

  • Use the latest challenge version with "type": "challenge@1.0".
  • Verify title and description.
  • Verify intro and finish pages.
  • Ensure in index.json there is a correct “title”, “text”, “verify” and “hint” for each step.
  • Ensure there is valid step_n.md, verify_n.sh, and hint_n.md file for each step.
  • Run linters for index.json, markdown, shellcheck (a shell script analysis tool) for .sh scripts, spelling and grammar checkers, and other linting tools that can verify other assets.
  • Ensure each step asks for a clear, measurable goal, but does not describe how the goal should be achieved.
  • Ensure each verification is precise. A goal can have multiple verifications and hints.
  • For each step, be sure there are no other ways a learner can achieve the goal without your verification picking up the valid state.
  • Scenarios often break later when 3rd part dependencies are missing precise versions or use “latest”. Ensure dependent versions are fixed.
  • Ask another person familiar with the technology to review the challenge.
  • Other producers need to quickly verify the challenge without being subject experts, so ensure a solutions.md and readme.md file has been provided.

As always, we appreciate your feedback on how we can make this an easier process for you.