How to write hints for multi-step VM exercises
How to write hints for multi-step VM exercises
Written by Maarten Van den Broeck
Updated over a week ago

To increase consistency in our hints between BI courses, consider the following guidelines on how to write good hints.

There are two types of hints in a multi-step VM exercise:

• Individual hints, one for each step of the exercise. These hints are shown when a learner asks for a hint during an instruction.

• A final hint. This is a single hint that is shown when a learner asks for a hint during the final question.

How much guidance should be given?

• Generally speaking, individual hints should help the learner to find at least half of the solution. They should contain help on all parts of the instruction, but should not reveal 100% of the solution.

• Example:

• Right-click on `Calculations` table and select New Measure.

• Enter `AvgProfit_x = AVERAGEX(Sales, Sales[LinePrice] - Sales[LineCost])` (Too much guidance)

• Good:

• Use the `AVERAGEX()` function that uses the `Sales` table and an expression that subtracts `LineCost` from `LinePrice`.

• The structure of the function should look like this: `AVERAGEX(<table>,<expression>)`

• The final hint should contain the (almost) full solution so that the learner can answer the question.

• Example:

• Your formula should look like this: `AvgProfit_x = AVERAGEX(Sales, Sales[____] - Sales[____])`. (Learners don’t know what to subtract)

• Good:

• Have you subtracted `LineCost` from `LinePrice` to calculate the average profit? Your formula should look like this: `AvgProfit_x = AVERAGEX(Sales, Sales[____] - Sales[____])`.

• Individual hints in the first chapter of a course or case study should contain more guidance compared to later chapters. This is to give learners the chance to get familiar with the course material.

• Introduction courses can give more guidance than intermediate or advanced courses. In introductory courses, we expect learners to have (almost) zero prerequisite knowledge of how to use a BI tool. That is why more guidance is suggested.

• As we encourage our users to think about how to complete an exercise themselves as much as possible, instructions are, generally speaking, action-based. In contrast, hints should be more specific and should contain details on where to click, what formulas to use… Hence, hints are more task-based instead. As a result, the formatting of hints will contain much more italics compared to instructions. See more details here.

Closing remarks

• When an exercise asks for a similar instruction as in a previous exercise, it is not required to repeat the hint twice. We expect learners to learn from previous exercises.

• Also, pay attention to writing good feedback messages when a learner submits a wrong answer. Feedback messages should help guide the learner in the right direction. Try to understand common mistakes a learner makes, and accommodate for this by adding custom feedback messages.

• Example: