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.mdandreadme.mdfile has been provided.
As always, we appreciate your feedback on how we can make this an easier process for you.