All Collections
Courses
Course Development
Instructions: best practices
Instructions: best practices

Some tips for writing good instructions in Coding, Iterative, and Sequential exercises.

Amy Peterson avatar
Written by Amy Peterson
Updated over a week ago

Instructions provide students with guidance for Coding, Iterative, and Sequential exercises. Ideally, instructions should build on top of the context, for example, if the learning objective of the exercise is to teach the use of a particular function or bit of code, your instructions should ask the student to use that. In general, however, you should not be too prescriptive about how the student solves the task. This is particularly true in courses targeting more advanced students. Furthermore, instructions should become less prescriptive within a given course or a given chapter. Ideally, the content will build upon itself and students will need less guidance towards the end.

Good ideas

Keep it simple. The guidelines limit you to 4 instructions and 480 characters (less than two Tweets). If you are struggling to keep within this limit, it's an indication that there is too much content in the exercise. Consider splitting it into two.

Wean the students off details. The first time new syntax is introduced, it's OK to give a detailed, hand-holding instruction. If a similar task is performed later on in the course, try to give less detail in the instructions.

Make sure the student is prepared. Any code that the student has to write should have been introduced at least twice before the student has to use it (in a video, and in the assignment text).

Mention the setup. If the pre-exercise code creates any variables or plots, it can be helpful to mention this fact at the start of the instructions.

Common problems and their solutions

Being too vague. Instructions need to be very specific about what they want the students to do. Vague instructions make it harder to test that the student has the correct answer, and can lead to frustration.

Copy and paste. One typical response to an exercise being too hard is to provide instructions that allow the student to copy and paste the answer. At this point, the student isn't learning anything, so this is discouraged.

Example

From Computing the covariance in "Statistical Thinking in Python (Part 1)". The function that is the exercise's focus, np.cov() is explicitly mentioned; but functions that have been seen before, like print(), are not.

  • Use np.cov() to compute the covariance matrix for the petal length (versicolor_petal_length) and width (versicolor_petal_width) of versicolor.

  • Print the covariance matrix.

  • Extract the covariance from entry [0,1] of the covariance matrix. Note that by symmetry, entry [1,0] is the same as entry [0,1].

  • Print the covariance.

Did this answer your question?