Instructions provide students with information required to solve the project. Ideally, instructions should build on the context provided in the Markdown cell of the Workspace notebook. In general, you should not be too prescriptive about how the student solves the project. The aim of the instructions is to provide enough information for advanced students to complete the project, while less experienced students may need to supplement with the Guides or Resources. If you are not familiar with using Markdown then please refer to this article.
Good ideas
Use one instruction for each key task that learners will need to complete. For example, one instruction could mention reading in the data and storing it as a Pandas DataFrame, and another states that learners will need to clean string data and convert to integers.
Utilize markdown syntax. For example, if you are referring to a variable then use backticks to render the name of the variable as code so it is clear to learners that this is part of the syntax they will need to use.
Common problems and their solutions
Being too vague. While instructions should allow learners to interpret what is needed and action in their own way, it is important to be specific about what the outcome should be. For example, if learners are required to use a specific model and performance metric, then rather than saying “Build a model using X to predict Y and evaluate the model’s performance” you should say “Build a logistic regression model using X to predict Y and evaluate performance by calculating the model’s f1 score.”.
Copy and paste. While it might be appropriate to include certain syntax, such as referring to a column name, you should avoid providing so much detail that learners can copy the instructions to execute the code required.