📜 Improve error message structure and consistency #5616
Conversation
FKEFFIEENFIENFFI
I tried to shorten them by using the requirements of Clarity and brevity requirements which are (aesthetic and minimalist design, recognition rather than recall). Meaning the errors should be shortened because students tend to not read the whole error so it should give out the critical info at the first part, that way a student can understand what it is going to say by not fully reading the whole sentence.
|
|
||
| msgid "Has Blanks" | ||
| msgstr "Your code is incomplete. It contains blanks that you have to replace with code." | ||
| msgstr "Code is incomplete. Try filling in blanks with code." |
There was a problem hiding this comment.
Putting this on this one but it is a general remark, I don't believe this is better. It feels very abrasive and short, I miss the "human communication" that we had before, this feel very much like communication with a machine. Can we make it more conversational?
|
|
||
| msgid "No Indentation" | ||
| msgstr "You used too few spaces in line {line_number}. You used {leading_spaces} spaces, which is not enough. Start every new block with {indent_size} spaces more than the line before." | ||
| msgstr "Insufficent {leading_spaces} spaces used on line {line_number}. Try increasing by {indent_size} for each new block." |
There was a problem hiding this comment.
Insufficient is a complex word! Maybe we should include target audience (10 and up) explicitly in the guidelines too and live by that?
Some suggestions on the first 7 error messages according to the given feedback
Felienne
changed the title
|
I like the new structure, thanks! Will we do wording (like Also (I am sure you know) tests are still failing, can you take a look? |
|
|
||
| msgid "Function Undefined" | ||
| msgstr "Function {name} used without being defined." | ||
| msgstr "We detected that a function {name} is being used without being defined. Can you define the function before it is used?" |
There was a problem hiding this comment.
Same thing with the backticks here, and replace a with the, because name will be replaced with an actual function name from the program.
|
|
||
| msgid "Missing Command" | ||
| msgstr "You missed a command on line {line_number}." | ||
| msgstr "We detected that the code seems to be missing a command on line {line_number}. Can you try looking at the exercise section to find which command to use?" |
There was a problem hiding this comment.
I find this suggestion interesting, there's not really something we call an exercise section, what did you mean by this?
|
|
||
| msgid "Missing Inner Command" | ||
| msgstr "It seems you missed a command for the `{command}` statement on line {line_number}." | ||
| msgstr "We detected that the code seems to be missing a command for the `{command}` statement on line {line_number}. Can you try looking at the exercise section to find which command to use?" |
There was a problem hiding this comment.
Please replace statement with command everywhere you see it, or also remove the word altogether.
|
|
||
| msgid "Wrong Number of Arguments" | ||
| msgstr "Wrong number of arguments for function {name}. Provided {used_number}, needs {defined_number}" | ||
| msgstr "We detected that function {name} has wrong number of arguments which is {used_number}. Can you try writing {defined_number} instead?" |
Felienne
changed the title
Co-authored-by: Jesús Pelay <45865185+jpelay@users.noreply.github.com>
Co-authored-by: Jesús Pelay <45865185+jpelay@users.noreply.github.com>
Co-authored-by: Jesús Pelay <45865185+jpelay@users.noreply.github.com>
Co-authored-by: Jesús Pelay <45865185+jpelay@users.noreply.github.com>
Co-authored-by: Jesús Pelay <45865185+jpelay@users.noreply.github.com>
|
Hi @jpelay! I am ok with all these changes, I am just not sure about the backtick doing what you think it does. If you can confirm it does, you may approve! |
Never mind, all cleared up now! |
|
Thank you for contributing! Your pull request is now going on the merge train (choo choo! Do not click update from main anymore, and be sure to allow changes to be pushed to your fork). |
|
Thank you for contributing! Your pull request is now going on the merge train (choo choo! Do not click update from main anymore, and be sure to allow changes to be pushed to your fork). |
Ohh sorry :c, I thought the backticks were necessary to show words as code in the error messages. What are they meant to do? |
I don't remember! Ok, I dove in a bit. I think you are right, partly, it does work like that, but there is also back-end magic involved as I thought, see here: Line 63 in 063d197 So it is not like just simple `` in markdown, which is what I remembered. |
Ahhhhh, I see! Thanks for clarifying! |
This pull request is part of a larger project in which we are redesigning our error messages according to these guidelines.
In this PR, I have worked on the redesigning topic (i) Structure. We aim to follow a consistent structure for all of our error messages. First sentence will inform our users of the issue, while the second sentence will offer a suggestion on how to resolve it. This approach helps users quickly understand where to look when something goes wrong and allows them to become accustomed to reading the error messages more efficiently due to their uniform structure. I added a suggestion on how to fix the problem for every error message while at it I also worked on (ii) Consistency. We aim to keep our error messages consistent by using the uniform wording and maintaining a similar sentence structure and length. Errors should follow the same format ensuring that the sentences start and end similarly. This consistency also aids in the readability and the structure of the error messages. because I was already creating new sentences while adding the suggestion and wanted to keep their wording consistent but the consistency aspect still needs some work for the future work.
Addresses #5012