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 on GitHub and Twitter. We also cover how to respond to Code of Conduct issues.

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

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:

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.

Twitter

Access

You can get access to the Pa11y Twitter account through Tweetdeck, and currently Rowan Manning is the right person to ask. DM him on Twitter. We don’t add everyone to the Twitter account, but we’re pretty trusting – if you’ve contributed in other areas and are getting involved in the project then it’ll be fine.

How/What to Tweet

The Twitter account should be low-noise, mostly announcements about new projects and new versions of existing ones (we’re looking into automating this). The Pa11y Twitter account should only ever retweet articles about Pa11y, not feedback and messages from users.

You can however respond to user questions/requests. In most cases, the appropriate action will be to point them at the correct documentation or ask them nicely to create a GitHub issue if they’ve found a problem.

The Twitter may also be used to bring certain GitHub issues or new web pages to the attention of a wider audience. This is useful for gathering feedback.

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:

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:

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:

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.