Comment Mapping Writing Tutorial

Introduction

JARS offers an automated solution to generating student course reports. However, automating means a lot of prep-work needs to be done. One of the hardest parts is to create a proper Comment Mapping. A comment mapping is simply a matrix table that maps a comment to a grade score, and the skills and assessment goal. The comment mapping also maps a comment to the grade score for both the opening sentence, and the closing sentence.

Example

A sample mapping is shown below:

S&A Item	A	B	C	D
Intro	{short_name} is an attentive and respectful student	{short_name} is an enthusiastic and respectful student	{short_name} is an attentive and friendly student	{short_name} is a friendly student
Shows good art expression	{pronoun} has an outstanding art expression	{pronoun} has a great art expression	{pronoun} has a good art expression	{pronoun} has a good art expression
Has a creative way of using art media	{pronoun} also has a creative way of using art media			However, {pronoun} needs more encouragement to improve {adjective} creative way of using art media
Is able to use art to express ideas and feelings	{pronoun} is also able to use art to express ideas and feelings	{pronoun} is also able to use art to express ideas and feelings		However, {pronoun} needs to improve {adjective} ability in expressing ideas through art
Has a good sense of colour which he or she applies to artwork	Moreover, {pronoun} also has an excellent sense of colour in {adjective} artwork	{pronoun} also has a good sense of colour in {adjective} artwork	However, {pronoun} also needs to develop {adjective} sense of colour more	However, {pronoun} also needs to develop {adjective} sense of colour more
Develops creativity			However, {pronoun} also needs to develop {adjective} creativity more	However, {pronoun} also needs to develop {adjective} creativity more
Closing	Keep up your good work, {short_name}!	Keep practicing, {short_name}!	Keep trying, {short_name}!	Keep trying, {short_name}!

So, for example if we have a student named "Fu". Fu scores as follows:

• Shows good art expression: A
• Has a creative way of using art media: B
• Is able to use art to express ideas and feelings: A
• Has a good sense of colour which he or she applies to artwork: C
• Develops creativity: C
• Overall Grade: A

The resulting comment will be:

Fu is an attentive and respectful student. She has an outstanding art expression, and she is able to use art to express ideas and feelings. However, she needs to develop her sense of colour more, and she also needs to develop her creativity more. Keep up your good work, Fu!

Let's see how the comment is generated step-by-step:
The system will first collect sentences from the comment mapping section. While collecting the sentences, the system will also detect which sentences are positive and which are negative (though this excludes the opening and closing sentences). Details on how the detection is done will be discussed further in the next section.

1. Map to correct introduction sentence:
   Since Fu received an Overall Grade of A the introduction sentence picked by the system will be:
   {short_name} is an attentive and respectful student
2. Map to correct sentence for "Shows good art expression":
   Since Fu received an grade of A for this particular S&A goal, the system will pick the following sentence:
   {pronoun} has an outstanding art expression (Positive Sentence)
3. Map to correct sentence for "Has a creative way of suing art media":
   Since Fu received an grade of B for this particular S&A goal, the system will pick the following sentence:
   (This section is empty so the system will not add any sentence for this part)
4. Map to correct sentence for "Is able to use art to express ideas and feelings":
   Since Fu received an grade of A for this particular S&A goal, the system will pick the following sentence:
   {pronoun} is also able to use art to express ideas and feelings (Positive Sentence)
5. Map to correct sentence for "Has a good sense of colour which he or she applies to artwork":
   Since Fu received an grade of C for this particular S&A goal, the system will pick the following sentence:
   However, {pronoun} also needs to develop {adjective} sense of colour more (Negative Sentence)
6. Map to correct sentence for "Develops creativity":
   Since Fu received an grade of C for this particular S&A goal, the system will pick the following sentence:
   However, {pronoun} also needs to develop {adjective} creativity more (Negative Sentence)
7. Map to correct closing sentence:
   Since Fu received an Overall Grade of A the introduction sentence picked by the system will be:
   Keep up your good work, {short_name}!

At the end of sentence collection, the system will have the following list of sentences:

opening_sentence = "{short_name} is an attentive and respectful student"

positive_sentences = [
    "{pronoun} has an outstanding art expression",
    "{pronoun} is also able to use art to express ideas and feelings",
]

negative_sentences = [
    "However, {pronoun} also needs to develop {adjective} sense of colour more",
    "{pronoun} also needs to develop {adjective} creativity more",
]

closing_sentence = "Keep up your good work, {short_name}!"

With the collected sentences, the system will assemble them into a positive and negative texts following a structuring algorithm which should result in the following list:

positive_text = "{pronoun} has an outstanding art expression, and {pronoun} is able to use art to express ideas and feelings"
negative_text = "However, {pronoun} needs to develop {adjective} sense of colour more, and {pronoun} also needs to develop {adjective} creativity more"

Then, the system will join all the texts and replace the keywords enclosed with the curly braces {} and transform them accordingly.

Note

Available keywords are discussed in the next section.

The result of the joining and keyword replacement is the final comment for the student.

How to create a proper mapping?

Comment Generator Workflow Must Knows

Creating a proper comment mapping is relatively simple once you are familiar with the workflow of the comment generator. Here are some key things to know about the comment generator workflow:

1. The generator reads from top to bottom. Hence, the comments will also be assembled in that order. So, try to read the mappings from top to bottom taking into account different grades for each S&A item.
2. Positive sentences are any sentences that do not start with However. Any sentence that begins with the word "However" will be considered a negative sentence. Further, the generator will remove subsequent occurrences of the word "However" and turn them into 'plain sentences'.
3. Negative sentences are always placed after positive sentences.
4. The generator ignores empty maps. You can utilize this to not provide a comment under certain conditions.
5. The generator supports more than 8 S&A goals. However, the generator works best when you have about 4–6 goals.
6. The generator generally removes the first occurrence of the word Also to prevent the text from having too many repetitive usages of "also". So, it is recommended to always add the word "also" where necessary because the generator will intelligently select when to use it and when to remove it.

Keywords

The comment generator currently supports the following keywords:

• {pronoun}: This will be transformed into He or She according to the student's gender, as listed in the grader report.
• {adjective}: This will be transformed into His or Her according to the student's gender, as listed in the grader report.
• {short_name}: This will be transformed into the student's nickname or short name as listed in the grader report.

Warning

• These keywords are case sensitive! Always use lowercase when typing in these keywords.
• The curly braces {} are required! If you omit them, they will not be transformed to the correct words.

Do It Yourself

Now that you know some key details in the workflow, try to make your own comment mapping.

Tip

Start off by writing the intro and closing sentences first because they generally don't need to be in logical sync with the rest of the items.

Comment structure and content

When writing the comments for an S&A goal, the contents of the comment generally reflect the goal to be achieved. For instance, if the goal is "Has a creative way of using art media", the comments will usually sound like the following sample sentences:

• {pronoun} also has a creative way of using art media (Positive)
• {pronoun} is also very creative in using various art media (Positive)
• (pronoun}'s creativity in using art media is outstanding (Positive)
• However, {pronoun} needs more encouragement to improve {adjective} creative way of using art media (Negative)
• However, {pronoun} needs to improve {adjective} ways of using creative media (Negative)

As mentioned above, there are two kinds of sentences: Positive and Negative. Negative sentences always start with "However". And, negative sentences are always placed after the positive sentences. So, plan accordingly which grade level for each goal will receive a negative comment. It is important to plan well to avoid having comments that are not cohesive.

Note

Negative comments should not always imply bad or very bad meanings. A negative comment can also be a constructive feedback.

Regarding sentence lengths, there are technically no limitations on how long a sentence can be. However, it is recommended to keep the sentences as concise as possible. As an unwritten rule, about 9–12 words (including keywords and conjunctions) should be the maximum number of words per mapped sentence. A concise sentence keeps the final length of the comment short. This will make the readers' lives more convenient because, at a glance, the comment looks less time-consuming to read. Having shorter but more concise sentences also means a lot more information regarding the student's achievement can be packed into the same comment length, which is beneficial for everyone.

Comment self-assembly

While laying out all the comments, try to read them from top to bottom as if you are assembling a comment for a student. Create an imaginary student as a persona and replace the keywords according to the persona's attributes (gender, name, etc.) to help you make the sentences clearer. This will help you know how the generated comments will be. Also, try to follow the logical structure of the grades. What is meant by this is to use scenarios that are as close as possible to real-life grades. This will help you ensure that the comment is cohesive.

For example:

• It is impossible for a student to have an overall grade of "A" but all his/her goal grades are marked "D".
• Generally (by rule at least) it is nearly impossible for a student who has a majority result of "A~B" to have one 'outlier' grade that falls into "D". Same goes the other way around. If a student performs bad (most of their grades are "D"), it is nearly impossible that there is one goal where they can obtain a grade of "A".

Tip

You can use the comment generator test suite to help you generate all possible combinations of comments. You can do this by:
Note: This tool requires the autocorrect feature to be usable (Java and Language Tool package must be installed)

1. Opening JARS
2. Start the Report Generator
3. Select your grader report file
4. On the bottom left of the window, there is a Test Comment Gen button. Click on that button to start the tool.
5. Once done, go to the folder where you store the grader report. There, you should find a new Excel file with the name of your grader report but with CGen_Test_ prepended in front of it. For example, if your grader report is called AAA.xlsm, the output file will be CGen_Test_AAA.xlsx.