Email templates with feedback instructions and reminders don't reflect our current policies and terminology

[contraexemplo]

If you're interested in the bigger context around this issue, I published a longer, more detailed report about it on my blog.

Context

Outreachy used to collect feedback from mentors and interns 3 times during the internship until a couple of cohorts ago:

• Initial feedback
• Midpoint feedback
• Final feedback

With the introduction of a fourth feedback cycle, we started referring to feedback cycles as Feedback 1-4 and we've established that only Feedback 1 and Feedback 3 are tied to stipend payment authorizations.

Issue at hand

Outreachy organizers often send automated emails to mentors and coordinators via organizer dashboard. Currently, when an Outreachy organizer sends an automated email to remind mentors to submit Feedback 4, they're sending an email based on the following template (home/templates/home/email/final-feedback-reminder.txt):

[URGENT] Mentor feedback required for final payment to {{ intern_selection.applicant.applicant.public_name }}

Please provide feedback on your intern through the Outreachy website. Their final feedback was due on {{ intern_selection.final_feedback_due|date:"M d, Y" }}. Their final ${{ current_round.finalpayment }} payment will be delayed until you provide feedback:

Causes

We have 4 email template files on home/templates/home/email referencing Feedback 4:

• home/templates/home/email/final-feedback-instructions.txt → Updated 2 years ago to remove wording about an intern's final stipend payment.
• home/templates/home/email/final-feedback-reminder.txt → Updated 5 years ago, and it still includes wording about an intern's final stipend payment.
• home/templates/home/email/feedback4-feedback-instructions.txt → Created to reflect our new feedback cycles.
• home/templates/home/email/feedback4-feedback-reminder.txt → Created to reflect our new feedback cycles.

The organizer dashboard is still using home/templates/home/email/final-feedback-reminder.txt as a template to remind mentors to submit Feedback 4, according to dashboard.py:

class FinalFeedbackInstructions(FeedbackInstructions):
    """
    Send final feedback instructions to mentors and interns.

    When: When final feedback forms open, and again if feedback is missing.
          Emails may be sent with an URGENT subject if feedback is late.
          Emails may be sent multiple times if there is a internship extension.

    Templates: home/templates/home/email/final-feedback-reminder.txt
               home/templates/home/email/final-feedback-instructions.txt
    """
    description = 'Final Feedback Reminder'
    slug = 'final-feedback-instructions'

    @staticmethod
    def due_date(current_round):
        return current_round.finalfeedback

    def generate_messages(self, current_round, connection):
        if not self.request.user.is_staff:
            raise PermissionDenied("You are not authorized to send reminder emails.")

        # Only get interns that are in good standing and
        # where a mentor or intern hasn't submitted feedback.
        interns = current_round.get_interns_with_open_final_feedback()

        for i in interns:
            email.feedback_email(i, self.request, "final", i.is_final_feedback_on_intern_past_due(), connection=connection)

Code in email.py makes it clear why that happens:

def feedback_email(intern_selection, request, stage, past_due, **kwargs):
    emails = []
    if past_due:
        emails.append(organizers)
        for m in intern_selection.mentors.all():
            emails.append(m.mentor.email_address())
        emails = emails + intern_selection.project.project_round.community.get_coordinator_email_list()
        template = 'home/email/' + stage + '-feedback-reminder.txt'

Possible solutions

Short term

Editing home/templates/home/email/final-feedback-reminder.txt. It should use the same language used on home/templates/home/email/feedback4-feedback-reminder.txt.

Long term

While trying to find the cause of this problem, I noticed that language around feedback cycles is quite convoluted. We often use old expressions such as "initial", "midpoint", and "final feedback". We need to reach an agreement on what terminology should be used, and update our code, website, and processes accordingly.

[contraexemplo]

Upon further inspection of other email templates related to feedback instructions and reminders, I realized all of our templates have issues with inconsistent wording and terminology:

• initial-feedback-instructions.txt still refers to Feedback 1 as "initial feedback". The subject line of initial-feedback-reminder.txt talks more explicitly about delays in the initial payment: "Mentor feedback required for initial payment to [public name]".
• feedback3-feedback-reminder.txt doesn't include a warning about payment delays on the subject or actual message. feedback3-feedback-instructions.txt doesn't mention that either even though this feedback cycle is tied to a payment authorization.
• midpoint-feedback-reminder.txt still referred to Feedback 2 as "mid-point feedback".

[contraexemplo]

Sage and I agree that changing that terminology across our codebase will take a huge refactor. Here are the more pressing issues for now:

• We have to decide what terminology we'll ultimately use
• We have to discuss how we'll refer to both stipend payments (should we keep it as "initial" and "final" stipend payments?)

[contraexemplo]

Our Internship Guide refers to the stipends as "$3000 stipend" and "$4000 stipend". My proposed solution is to use "Mentor feedback [1 or 3] required for stipend payment to [Public name]" on the subject line and use ${{ current_round.initialpayment }} and ${{ current_round.finalpayment }} on the actual message.