This page distills best practices for crafting learner-friendly hints in Epi-Workbench coding exercises. It outlines the hint-block syntax, clarifies Knowledge Point deductions, and offers guidance on titles, question-based nudges, and solution reveals. By adopting these conventions, hints strike the right balance between support and challenge, keeping learners motivated while safeguarding the discovery process.

• Syntax
• Hint Titles
• KP Deductions
• Writing Helpful Hints
• CST Feedback vs. Hints
• Hint Appendix

Hints can be added below any code block using the following format:

# Hypothetical test code block.
# Write hints below the test code block using the syntax shown above.
x <- "hint"

<!-- HINT:
[TITLE=Writing Hints, POINTS=25]
- Hints provide supportive nudges that guide learners toward the solution without giving away the answer.
- Hints should guide, not give away. Whenever possible, frame hints as leading questions that encourage critical thinking and recall. However, when a concept is new or particularly complex, it's okay to be more direct.
- Use questions when learners should be expected to reason or recall: "Did you remember to group the data before summarizing?"
- Use directives when the focus is syntax or when getting stuck would feel arbitrary: "Use the n() function to count the number of rows in each group."

[TITLE=Adjust Hints, POINTS=25]
- Adjust the depth and directness of hints based on the type and difficulty of the lesson:
  - Intro-level exercises: Direct, supportive guidance — include syntax or function names.
  - Intermediate lessons: Leading questions and strategic nudges.
  - Labs: Clarifying process or logic — minimal syntax help.
  - Culminating exercises: Minimal hints. Focus on breaking down the task, not how to code it.
- When in doubt, ask: What would keep the learner making progress without short-circuiting the learning opportunity?

[TITLE=Hint Titles, POINTS=25]
- Hint titles should be brief and written in title case.
- Ask yourself, “Would this title help a learner pick the right hint to view?” If not, it might not be needed.
- The final (or possibly only) hint containing the solution code should always have the title "Solution".

[TITLE=Solution, POINTS=100]
- The final hint will be the solution. It should remove the remainder of the points.
- Wrap solution code with code fences:
```
x <- "hint"
```
-->

By default, line breaks (carriage returns) are stripped from code when displayed inside hint blocks. This can make longer or multi-line solutions difficult to read, especially in final [TITLE=Solution] blocks.

To preserve the original formatting and improve readability, wrap the code in triple backticks (```) inside the hint bullet. This will display the code in a fixed-width block with line breaks intact.

❌ Without backticks (flattened display)

[TITLE=Solution, POINTS=100]
tibble(mean   = mean(cd4_counts), median = median(cd4_counts), mode   = mode(cd4_counts), sd     = sd(cd4_counts), min    = min(cd4_counts), max    = max(cd4_counts))

✅ With backticks (preserves formatting)

[TITLE=Solution, POINTS=100]
tibble(
  mean = mean(cd4_counts),
  median = median(cd4_counts),
  mode = mode(cd4_counts),
  sd = sd(cd4_counts),
  min = min(cd4_counts),
  max = max(cd4_counts)
)

Top

Hint titles are optional but encouraged, especially when a coding exercise includes multiple, non-sequential hints. A well-written title helps learners choose the hint that best aligns with the part of the task they’re struggling with — reducing confusion and improving efficiency.

✅ When to Use Titles

• The final (or possibly only) hint containing the solution code should always have the title "Solution".

• Use a title when there are multiple independent hints and learners may benefit from knowing which code block or section each hint addresses.

• Titles are helpful for multi-blank code blocks, especially when hints don't build on one another.

• If a hint is part of a linear, scaffolded sequence of hints that build on each other (e.g., where you might otherwise write "Hint 1", "Hint 2", etc.), a title may be omitted to avoid redundancy.

• If the exercise has only one hint (in addition to the solution), a title may be omitted.

🔎 Tip: Ask yourself, “Would this title help a learner pick the right hint to view?” If not, it might not be needed.

🧠 Title Content Guidelines

• Write in title case

• Keep it brief — no more than a few words

• Use titles that describe which part of the code block or task the hint applies to (e.g., a specific blank, argument, or step)

• Avoid vague, conversational, or numbered titles unless they aid clarity

🤔 About Titles Like “First Blank,” “Second Blank”

• These titles are clear and functional for short, multi-blank code blocks where:

  • Each blank is independent

  • The order matters

  • It’s not practical to describe the blank in a more semantic way

However, consider more descriptive titles if space allows — e.g., “File Name Argument” or “Missing Value Parameter”. These improve transparency without requiring learners to count blanks or interpret order.

✅ Acceptable:
[TITLE=First Blank, POINTS=25]
[TITLE=Second Blank, POINTS=25]

✅ Possibly better:
[TITLE=First Blank - Read Function, POINTS=25]
[TITLE=Second Blank - col_positions Argument, POINTS=25]

✅ Examples of Good Titles

[TITLE=Check File Name, POINTS=25]
[TITLE=Set Working Directory, POINTS=25]
[TITLE=Wrap With Quotes, POINTS=25]
[TITLE=Solution, POINTS=100]

Use bullets sparingly to reduce cognitive load when:

• Listing multiple acceptable approaches or key functions

• Breaking down a multi-step task into simpler parts

Do:

<!-- HINT:
[POINTS=50]
- Use `mean()` to compute the average.
- You might also consider `median()` if the data are skewed.

[TITLE=Solution, POINTS=100]
- mean(x)
- median(x)
-->

Top

Don’t:

• Overload bullets with full code chunks

• Use bullets for tasks that could be better phrased as single-sentence questions

Epi-Workbench uses Knowledge Points (KP) to reward persistence and reduce the pressure of getting things right on the first try. Learners are only penalized for the hints they view, and there's a built-in safeguard that prevents their KP from going negative.

To ensure consistency and fairness across exercises, please follow these scoring rules:

• Hints can be viewed in any order.
• Learners are only penalized for hints they open.
• The maximum total KP deduction is always 100, regardless of how many hints are viewed.
• Each hint should specify its point deduction using the [POINTS=...] tag.
• A hint's point deduction = 100 / total number of hints in that exercise.
• Always include a final solution hint with [TITLE=Solution, POINTS=100].
• Even if all hints are viewed, the total KP deduction is capped at 100.

📌 Important: The [TITLE=Solution, POINTS=100] block should always be the final hint in the block and should present the full, correct solution.

✅ Example:

If an exercise has 4 hints total (3 scaffolding hints + 1 solution), each scaffold hint is worth 25 points:

<!-- HINT:
[POINTS=25]
Make sure the file name matches exactly, including the extension.

[POINTS=25]
The file you need is called "Alcohol Study 1.xls".

[POINTS=25]
Remember to wrap the file name in quotes.

[TITLE=Solution, POINTS=100]
alc_1 <- read_excel("Alcohol Study 1.xls")
-->

Learner KP Deductions (Using This Example)

Top

Hints provide supportive nudges that guide learners toward the solution without giving away the answer. They are especially useful when learners are stuck, introducing new concepts, or working on multi-step tasks.

Hints should guide, not give away. Whenever possible, frame hints as leading questions that encourage critical thinking and recall. However, when a concept is new or particularly complex, it's okay to be more direct.

• Use questions when learners should be expected to reason or recall:
  • "Did you remember to group the data before summarizing?"
• Use directives when the focus is syntax or when getting stuck would feel arbitrary:
  • "Use the n() function to count the number of rows in each group."
• Avoid giving full answers unless the goal is to reduce frustration and keep momentum in early or scaffolded exercises.

✅ Recommended balance: Hints should move learners one step closer to the solution, not all the way there (except in early lessons or after several failed attempts).

Adjust the depth and directness of hints based on the type and difficulty of the lesson:

🪄 When in doubt, ask: What would keep the learner making progress without short-circuiting the learning opportunity?

Think of CST feedback as a polite tap on the shoulder and hints as a clue after raising your hand.

Top

<!-- HINT:
[POINTS=0]
- This code block already contains the correct code. Please submit it without making any changes.
- If you accidentally modified the code, click the reset button (🔄) on the toolbar to restore the original version.
- Want to experiment or try something different? Open the interactive code console (</>) to explore safely without affecting your submission.
-->

Top