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.
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.
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.
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.
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:
- 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
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:
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. Twitter, 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 (Twitter, 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.
You must never reveal information about a reporter outside of the group you originally form to deal with the report.