Feedback Strings Overview
- Overview
- Preparing New Feedback Strings
- Adding New Feedback Strings
- Updating / Revising Existing Feedback Strings
- Tangent: Adding XML Blocks To Feedback Strings
Feedback Strings are the pieces of feedback a student sees when they fail a level
These feedback strings appear in the same window as the level instructions and authored hints, both of which can be edited on the level edit page. However: Feedback strings cannot be added or edited from the level edit page!
Instead, they are kept in a separate file here: en_us.json. This is because many feedback strings are translated into different languages (example here). In order to change or update these strings, there's a special process to go through (more on that later).
These feedback strings are set up as an object with a {key: value} relationship.
{
"addAdditionalPrompts": "Your program didn't create enough prompts."
}- The
keyis also a string which is a shorthand identifier for each feedback string. These need to be unique!- In the example above,
addAdditionalPromptsis the key
- In the example above,
- The
valueis what's actually displayed to students.- In the example above,
"Your program didn't create enough prompts."is the value (and what is displayed to students)
- In the example above,
To add a feedback string to your level, you first need to add some validation code (click here for an overview of validation in Sprite Lab). At the end of your addCriteria() function, you tell it the feedback string key that you want to use. Then the level will find that key and use it when a student fails the level. If the key doesn't exist, a generic "Something's wrong with your code!" feedback message will appear.
(^ that gif may take a bit to load)
As you develop levels in Sprite Lab, it can be useful to prepare potential feedback strings as you're developing levels even if you're not writing validation code yet. Then eventually, you'll need to ask our engineering team for help updating these feedback strings for students. And then as you get feedback on levels or discover typos, you may need to update or revise existing feedback strings. The rest of this article breaks this process into the following steps:
- Preparing New Feedback Strings
- Adding New Feedback Strings
- Updating / Revising Existing Feedback Strings
Key Resource: Validation Strings Interactive Spreadsheet
As you're developing levels or writing validation code, you can use the spreadsheet above to stage your updates.
- Create a new tab at the bottom for the lesson/module you're revising
- Add a row for each feedback string
{key: value}pair you want to add
As you're writing validation code, include the feedback string as you write your levels.
- Technically the feedback string won't appear until the next step, but for now you're future-proofing your levels: once the feedback string is updated, all of your levels will magically include it in their feedback
- This also means you shouldn't change the key of a feedback string once it's in a level!
Summary: By this point...
- Your feedback strings are in their own tab in the spreadsheet
- The keys for your feedback strings are in levels, but the feedback strings don't actually appear yet.
Prerequisite: You need to have a Github account and you need to be added as a contributor to the code-dot-org Github repository. As of writing this, Jessica K is the person who handles this - you can ping her and ask her to set you up with the same permissions as the other curriculum writers. Make sure your account has your name in the profile somewhere so engineers know that the account is associated with someone at Code.org.
- If you end up creating a GitHub account: make sure you enable two-factor authentication for it
Follow these steps to add new feedback strings. If you need to update / revise feedback strings: try to keep that separate from adding new ones, and see the next section instead.
By now, you should have a new "Pull Request" (PR) and the URL for the GitHub website should look like https://github.com/code-dot-org/code-dot-org/pull/#####, where ##### is a number.
When you first create this PR, there's a section for 'continuous integration'
Check back at this URL in ~2 hours and see if the continuous-integration section has finished running:
Once it's finished and passed: post in #student-learning and ask someone to review your PR
Once it's reviewed and the PR has all green checks: follow up in #student-learning and ask someone to merge the PR. Only an engineer can merge these changes - otherwise, they'll just sit waiting in a "draft" stage.
Once it's merged, it will get deployed on the following day. You can verify if a feedback string is available to students by using this Feedback String Preview Widget
But wait - it's possible someone will give you feedback on the strings / catch typos / etc
If that happens: don't worry about fixing it in the PR. Instead, make a note of it and prepare to resolve it in the next section
Prerequisite: You need to have a Github account and you need to be added as a contributor to the code-dot-org Github repository. As of writing this, Jessie K is the person who handles this - you can ping her and ask her to set you up with the same permissions as the other curriculum writers.
- If you end up creating a GitHub account: make sure you enable two-factor authentication for it
Prerequisite: Review the steps above, since this section is very similar
To update feedback strings:
- Follow the steps in Part 1: Exporting Validation Strings to import the existing feedback strings (Steps 1-3)
- Once the existing strings are imported: update any of the feedback strings directly in this sheet
- Export the feedback strings using Steps 11-14 in Part 1: Exporting Validation Strings
- Do all of Part 2: Creating the Update Request as written. If you can, in Step 12 when describing the Pull Request: indicate that these should only be changes/updates to existing strings
- Continue the same process as above to ensure the strings are given feedback and merged
Once it's merged, it will get deployed on the following day. You can verify if a feedback string is available to students by using this Feedback String Preview Widget
Feedback strings can contain XML blocks as well. In the Validation Strings Interactive Spreadsheet, they can appear expanded (yellow) or inline (green):
Getting the XML incorrect can lead to an awkward experience for students, so it's a good idea to test the XML first. Here's a way to do that:
- Create the block(s) you want to use in an empty levelbuilder level, then highlight it
- In the Extra Links menu, select "Copy Selected Block to Clipboard"
- Go to edit the level you're in and find the Authored Hints section. Type
<xml></xml>into the box.
- Paste the code you copied from the level in-between the
<xml></xml>tags
- Scroll down to Authored Hints JSON. Copy the
"hint_markdown"value EXCEPT the starting and ending quotes
- Go to the Feedback String spreadsheet and paste it into the feedback string you want to use.