Skip to content

Latest commit

 

History

History
37 lines (24 loc) · 2.36 KB

tone_guide.adoc

File metadata and controls

37 lines (24 loc) · 2.36 KB

Tone Guide

When writing a rule, we must consider who we are talking to, what they are trying to achieve, and what their mindset is likely to be.

Who are we talking to?

We will be talking to a range of people; experienced engineers fixing something for the 10th time, people very new to the language, working on code they don’t know well, and everyone in between. It is also important to realize that many of our users are not native English speakers.

What might they be doing, and how do they feel?

  • They want to merge a PR and have a failing quality gate

    • They may be tired, stressed, embarrassed, or under pressure to finish

      • Now is the time for a calm, well-informed mentor or coach, not for criticism, fear, or excessive humor

  • They just saw they have a potential security hole

    • They may be worrying about the implications for their job or getting a reprimand from a stern boss or security owner. They may be thinking this is yet another false positive and hovering over the ‘won’t fix’ button.

      • We need to be calm and factual. There is no need to scare them unduly and a friendly tone will definitely be helpful.

  • They got that green quality gate, are basking in their success, and considering what to do next

    • How can we help them turn that cheerful glow into motivation to learn more?

Guidelines

Tone: We are your coding mentor. We are friendly and trustworthy but reasonably serious; we know what we are talking about, and we want to help you make the right change and grow in the process, at the right time for you.

  • Aim for brevity and clarity in the 'Why is this an issue' and 'How to fix it' sections.

    • Aim for just enough to make it clear what the key points are and no more. You can always add interesting stuff to the 'more info' section for when they have some spare time and want to learn more.

    • Try to use simple English and avoid slang. Assume users have high school-level English, equivalent to CEFR levels B1/B2, at best. How easy can we make it to understand complex ideas?

  • Write in the active voice rather than the passive.

    • 'The user logged into their account,' not 'The account was logged into by the user.'

  • Try to avoid unnecessary jargon

    • If in doubt, explain it or link to a good explanation

  • Try to be positive

    • We want them to understand the facts but not scare them unnecessarily. We are part of the solution, not the problem.