Communications

Hello, so you’re interested in helping out with our communications? We’re pretty pleased about that. This guide covers general writing style as well as everything you need to start talking to our users. We also cover how to respond to Code of Conduct issues.

• Writing style
• GitHub
• Code of conduct

Writing Style

We don’t have strict guidelines on how you should write. We’re not going to attempt to remove your personality from your writing. We have two sets of guidelines - Tone of Voice and Plain English.

Tone of voice guidelines

• Write like a human

  Be professional, yes, but also conversational. We don’t want to sound like robots, and should certainly never be communicating on behalf of the Pa11y project in unfeeling business-speak. At all times our users should feel like they’re talking to a regular human.

• But a nice human

  Be friendly, even if the user you’re speaking to is being difficult (excluding when there’s a Code of Conduct violation). Our users are giving up time and energy to make their sites more accessible, and potentially contributing back.

• Be thankful…

  Make sure you thank anyone who’s made a contribution or is even simply using Pa11y (when it feels appropriate).

• …especially to our contributors

  Our contributors are amazing – they’re giving up their time to make the web as a whole more accessible. Our gratefulness should definitely come across, as long is it’s not overbearing!

• Even in documentation

  We’re not saying that the documentation should read like a conversation, as this would make technical content imprecise. However introductions and any signposting should be friendly and helpful.

Plain English guidelines

Follow Plain English guidelines to help safeguard the accessibility of your written content. It’d be ironic for an a11y project to produce documents that are hard to understand! All relevant guidelines for writing well apply. You might find tools like Hemingway App helpful when editing. In particular:

• Be concise
  • Check any sentences with more than 25 words to see if you can split them to make them clearer.
  • Use contractions (e.g. “can’t”, “it’s”).
  • Go straight to the point.
• Be specific
  • Use the active voice instead of the passive voice (e.g. “NPM will install the dependencies” instead of “the dependencies will be installed”).
  • Address the user as “you” where possible.
  • Avoid referring to “things” or “stuff”.
  • Be direct. Avoid metaphor, simile, and slang.
• Be informative
  • Consider your audience. General information may not look the same as information aimed at a technical audience.
  • Be as precise as you can usefully be - consider linking to high-quality external resources where relevant.

GitHub

Access

All of the Pa11y projects are open source, and contributing does not require access to the GitHub organisation. If you do need access to create or administer a repo, contact us (Rowan Manning might be the best person to ask).

Responding to issues and PRs

Ideally, one of us should respond to issues and pull requests within the first day of opening. That doesn’t mean that they need to be actioned, and a response can be as simple as:

Hi, thanks for opening! We’re looking into it.

If you have write access to repositories, we make extensive use of issue labels; an ideal first response is adding labels. This gives a user or contributor the message that we’re paying attention, and that we are organised.

If a particular team member is ideally suited to resolve an issue or review a pull request, then feel free to assign them to it. When doing this, it may also be polite to add a comment @mentioning them so that they know why they’ve been assigned.

If an issue is a duplicate of an older issue, the simplest response is:

Hey [person], a similar issue’s been opened before: [link-to-issue]

Then you can add the “duplicate” label and close the issue.

How to say no

Sometimes we have to say no to a feature request. That’s difficult. Sometimes we have to say no to a pull request, and that’s even harder! As a user or contributor it’s natural to get defensive in this scenario, so it’s our job as maintainers to ensure that they still feel valued.

You should always explain why you’re saying no, this also gives you a point of reference if a feature request comes up again in future.

Code of conduct

Responding to Code of Conduct issues and violations is really important. Not only do we need to do so promptly, but we need to make sure that core contributors are prepared to take necessary action.

Receipt and information gathering

If you receive a report, the first thing you should do is reply to the report to confirm receipt. This should be sent within 24 hours, and should simply thank the reporter for speaking out and assure them that their report is being dealt with.

If the following information is not volunteered in the written or verbal report, ask for it/include it, but do not pressure the reporter:

• Identifying information of the person in violation of the Code of Conduct
• The behavior that was in violation
• The approximate time of the behavior (if different than the time the report was made)
• The circumstances surrounding the incident
• Other people involved in the incident

Discussion

The next step is to work out who else within the core team to involve. It’s very important that if a core team member is being reported, that you do not involve that team member in the discussions (no matter who that team member is).

Now that you have at least one other core team member in the loop, you should discuss the report with them (not responding to the original issue yet). This reduces the chance of any one person’s biases from affecting the outcome. You should take the following into account when assessing a report:

• The reporter is being brave by coming to you
• It’s extremely unlikely to be a false accusation

Resolution

When you’ve come to a decision on whether the reported behavior violates the Code of Conduct, you’ll need to decide on a resolution. Regardless of what action you take, the reporter should never be identified to the individual who is being reported. Possible resolutions include:

• Taking no further action (if it’s determined that no violation occurred).

• A private reprimand to the individual(s) involved. In this case, all core team members involved in the decision should be copied in.

• A public reprimand. This should happen in the same place as the violation, e.g. Slack, GitHub.

• An imposed vacation (i.e. asking someone to “take a week off” from a the GitHub repos, Slack, etc.). You should communicate this “vacation” to the individual(s). They’ll be asked to take this vacation voluntarily, but if they don’t agree then a temporary ban may be imposed to enforce this vacation.

• A permanent or temporary ban from some or all project spaces (Slack, GitHub, etc.). You should maintain records of all such bans so that they may be reviewed in the future and extended to any new project spaces.

• A request for a public or private apology. You may attach “strings” to this request, e.g. you may ask a violator to apologize in order to retain their membership on Slack.

Once a resolution is agreed upon, but before it is enacted, you should contact the original reporter and any other affected parties and explain the proposed resolution. You should ask if the resolution is acceptable, and take note of feedback.

Confidentiality

You must never reveal information about a reporter outside of the group you originally form to deal with the report.