Facilitating
A welcoming community is an investment into the future and reputation of the Health NZ API Standards. It is important to give contributors a positive experience, and to make it easy for them to keep coming back.
As we build the community, consider how someone who is just starting to use the Standards might get involved. As a moderator, your goal is to reduce the friction and make it easy for contributors to get involved and stay involved.
When people feel welcome and can quickly get things done, they will feel good about contributing and will want to do more.
As a moderator of the community, your job is to foster productive conversations, promote healthy collaboration, and de-escalate conflict when things get heated or off topic.
These principles and the following sections provide some guidance for community moderators.
| Principle | Description |
|---|---|
| Be kind, but firm | Discussions should be forthright, but they must remain respectful. You will set the tone for the community. Set a good example. |
| Critique is goodness | Contributors have taken the time to review and respond so embrace constructive criticism and try to stay away from defensive comments. |
| Rely on others | If the topic is outside your area of expertise and experience, bring in others who can help. |
| Be concise enough | Short and sweet isn't always sufficient so be verbose where it increases clarity. Be sure to define any acronyms you use so everyone knows exactly what you mean by your TLA. |
| Keep asking “why?” | Try to understand the reasoning behind an issue or a proposed change. Encourage the community to have different perspectives because, in the end, this will improve the outcome. |
| Stick to the facts | A solution to an issue that is supported by assumptions and anecdotal evidence is often a poor solution. Gather data to support the premise of the issue and only then decide the best course of action to take. |
| Focus on value | If the benefit of resolving an issue outweighs the complexity of solving it, it's best to lower the priority and move on. |
How to effectively moderate the community
Don’t tolerate bad actors
As a moderator, you establish the guidelines for your community and are responsible for enforcing them according to the rules set forth in the code of conduct.
Unfortunately, the project will inevitably attract disruptive people. They may start unnecessary debates, quibble over trivial features, or bully others.
Do your best to adopt a zero-tolerance policy towards this type of behaviour. If left unchecked, this behaviour can make other people in your community uncomfortable and prevent new people from participating.
When you see negative behavior happening on your project, call it out publicly. Explain, in a kind but firm tone, why their behavior is not acceptable. The Code of Conduct is a constructive guide for these conversations.
Also, refer to GitHub's Managing disruptive contributors for information about hiding, editing and deleting comments.
Eventually, if a contributor is not willing to abide by the Code of Conduct, you should follow the Enforcement Guidelines to manage them out of the community.
Be transparent and keep communication public
Whenever you can, keep communication about your project public. If somebody tries to contact you privately to discuss a feature request or support need, politely direct them to the public community forums.
Sometimes discussions happen offline (i.e. working groups) or matters are discussed in private (i.e. with members of the Standards Oversight Forum). Document these conversations in public so the community is kept informed. For example, post the notes of a conversations or document any decisions reached.
An added bonus, anybody who joins the community will have access to the same information as someone who’s been there for years.
Encourage action over discussion
Discussion is important, but there is a difference between a productive and an unproductive conversation.
By all means, encourage discussion so long as it is actively moving towards resolution, but don't allow conversations to languish. Good questions to ask yourself are:
- How does this bring us closer to a resolution?
- What steps should we take next?
- Do we have enough information to propose a solution idea?
If a conversation clearly isn’t going anywhere, there are no clear actions to be taken, or the appropriate action has already been taken, close the issue and explain why you closed it.
Be responsive, even if the answer is no
When people take the time to contribute, it is only polite to respond in a timely manner. Try to be responsive when someone opens an issue, submits a pull request, or asks a question about the Standards. When you respond quickly, people will feel they are part of a dialogue, and they’ll be more enthusiastic about participating.
The Participating section indicates the expected timeline for responses. If you aren't able to keep to this timeline, update it so the community knows what to expect.
Don’t leave an unsuitable contribution open because you feel guilty or want to be nice. Ignoring contributions sends a negative signal to the community.
If you don’t want to accept a contribution:
- Thank them for their contribution
- Explain why it isn't being accepted, and offer clear suggestions for improvement, if you’re able.
- Link to relevant documentation, if you have it.
- Close the item
Sometimes, a contributor may get upset or criticise your decision. If their behavior becomes inappropriate refer to Don't tolerate bad actors
Be proactive
We've written various guidelines and other documents to guide the community. As the community grows, moderating will become more complex and you'll need to consider improvements to make things easier to manage. Refer to GitHub's setting up for health contributions for some ideas.
For example, we've written the Get Involved section to explain the process for submitting issues and PRs and to describe the potential outcomes of any contributions.
If the project is receiving too many low-quality contributions, don't be afraid to update the Get Involved section to add additional requirements. For example, you might believe that quality will be improved by requiring an open issue for discussion before a pull request can be raised.
If you think it will help, add new templates for issues and pull requests, or improve the existing templates in response to recurring themes in the community.
If you keep the documentation up to date and community members don't follow the rules, you can immediately close their issue and point to your documentation.
While this approach may feel unkind at first, being proactive is actually good for all parties. It reduces the chance that someone will waste time on a low priority item. Plus, it makes your moderator workload easier to manage.
Facilitation and moderation responsibilities
Community members will feel comfortable to contribute if the discussion forum is well run, active and welcoming. Facilitators are one of the groups responsible for ensuring that discussion is relevant and on topic, which means keeping aware of how discussions are progressing, as well as what the specific technical topics under discussion are. Facilitators are expected to guide the community through:
Monitoring conversation
This means taking an active role in all discussions going on in the community and not just the ones they are brought into. Functions that a facilitator will perform include;
- Labelling - checking that labels on discussions are accurate and potentially creating new labels for others. Labels make it easier for members to find relevant material and helps keep discussions on track.
- Closing duplicates - helping to consolidate issues if the same topic has been raised multiple times.
- Identifying participation opportunities - looking to get other people involved if they have missed a discussion or issue to create good responses from the wider community.
- Enforcing the community guidelines - identifying where members may need reminding of the community guidelines, especially the code of conduct, and, if required, following the enforcement guidelines to curtail poor behaviour.
Encouraging participation
Active discussion doesn't always just happen - it needs to be helped by people leading and encouraging others who may be reluctant to get involved. Facilitators are expected to;
- Celebrate contribution - thank people for their input and show that they are being listened to and welcomed.
- Actively seek contribution - find ways of enrolling new and existing members into a discussion to get multiple perspectives.
- Create opportunities for discussion - creating discussions or raising questions to prompt further discussion makes it easier for people to contribute.
Identifying issues
Identifying potential issues for others requires taking a community wide perspective of issues and finding relationships between topics and work done by other people. Thinking about the implications of a discussion may cause additional topic areas to be identified or, it may help to enrol other parties who may be affected into a discussion. Facilitators should be looking for such relationships and drawing them to attention.
Identifying items for more attention
Ideas can come from anywhere and may require a wider group to get involved. Items, such as issues, may need wider participation so sometimes simply encouraging relevant SMEs within the community to participate in the conversation is enough. Some items which need even more attention can also be tagged with sof-agenda so they will be discussed at the next SOF meeting, where a working group might be formed to address the item.
Facilitators should be looking for well considered, yet speedy, resolution to issues by encouraging participation and raising them to the SOF, as required, to get the right level of input.
Preparing for SOF meetings
The community will identify issues that they feel require input or decisions from the SOF. Contributors are advised to add a label of sof-agenda to their proposals when they require SOF input or are ready for SOF consideration. Preparation for the SOF meeting is to search for all sof-agenda items and adding them to the meeting agenda. There may be other items to be added from previous meetings or items identified by SOF members.
A standard meeting agenda to review previous minutes, review proposals from the community, review overall progress and direction should be prepared and circulated to all SOF members ahead of the meeting. The agenda is also to be published for community visibility so they can see if items were accepted, referred for further work or were declined - and the reasons why.
Providing guidance and support
Members may not be familiar with the tools or resources to help raise questions, issues or suggestions. Facilitators should make it easy for people to be directed to the right place or people to get help. Members have an interest in APIs for the Health Sector and the goal is to make it easy for them to create or use more APIs.
Publishing minutes for the SOF meetings
In keeping with the desire to be transparent and to keep communication public, facilitators should ensure minutes for the Standards Oversight Forum (SOF) are published as a discussion item in the GitHub repository. Be sure to use the sof-minutes label so they are easy for community members to find.
Use available tools and guidance
GitHub has numerous tools to help moderators with their activities. Use them.
GitHub and Open Source have loads of guidance on how to administer and manage a community, such as: