Skip to content
This repository has been archived by the owner on Sep 24, 2022. It is now read-only.

Code of conduct template set #246

Open
wants to merge 8 commits into
base: dev
Choose a base branch
from

Conversation

barbaricyawps
Copy link
Contributor

@barbaricyawps barbaricyawps commented May 5, 2022

Pull request summary

The Code of Conduct templates are intended to be used together. As such, it includes the following files:

  • A template-code-of conduct.md file for creating a Code of Conduct.
  • A template-code-of-conduct-response-plan.md for creating a Code of Conduct response policy and procedures.
  • A template-code-of-conduct-incident-record.md that is filled out when a community moderator takes an incident report from a community members.
  • A template-code-of-conduct-remediation-record.md that is filled out when a community moderator meets with a community member to explain the consequences of a Code of Conduct violation.
  • The following guides:
    • guide-code-of-conduct.md
    • guide-code-of-conduct-response-plan.md
    • guide-code-of-conduct-incident-record.md
    • guide-code-of-conduct-remediation-record

This template set was created as part of the Community Docs working group, co-led by @deanna-cs and myself.

Template contributor checklist

IMPORTANT: The next three sections in this checklist should be filled out by the template contributor at the time they submit this request.

NOTE: Pull requests can only be merged when all boxes are checked.

Which issue does this pull request fix or reference?

This pull request:

Procedural requirements

  • The template contributor participated in a template working group to create this template.
  • This template was submitted to the community for feedback.
  • A template mentor approved this template set to move to the pull request phase.

Template set requirements

  • Template file is present.
  • Template guide is present.
  • Template deep dive is present (optional).
  • Template example is present (optional).
  • If the optional template example is not present, open a new issue to track this task in the Chronologue repository, then include the link here.

Template pull request reviewer checklist

IMPORTANT: The rest of the sections in this checklist should only be filled out by authorized Good Docs Project pull request reviewers. If you are the individual template contributor, do not fill out the rest of the fields or check the boxes.

NOTE: Pull requests can only be merged when all boxes are checked.

Mechanics and formatting requirements - PULL REQUEST REVIEWER ONLY

  • Check rendered Markdown output to ensure it renders correctly.
  • Review the template set to ensure all documents follow the template markdown style guide.
  • The template set is free from grammar errors and typos.

Overall usability - PULL REQUEST REVIEWER ONLY

  • The scope of the template set is appropriate, meaning it is not too simple or overly complex (i.e. it needs to be expanded or broken into multiple smaller templates).
  • The template is complete and comprehensive.
  • The template set is well-organized and the contents flow in a logical order.
  • The template is well-written and clear.
  • The template set provides sufficient guidance about how to fill it in and implement the template in a documentation project.

Template file requirements - PULL REQUEST REVIEWER ONLY

  • Check rendered Markdown output to ensure it renders correctly and follows the template markdown style guide.
  • The template title is present and is an H1.
  • The template includes an introductory comment mentioning the other template resources (such as the guide).
  • Embedded writing tips are formatted with {curly brackets}.
  • The template is free from grammar errors and typos.
  • The scope of the template is appropriate, meaning it is not too simple or overly complex (i.e. it needs to be expanded or broken into multiple smaller templates).
  • The template is complete and comprehensive.
  • The template is well-organized and the contents flow in a logical order.
  • The template is well-written and clear.

Template guide requirements - PULL REQUEST REVIEWER ONLY

  • Check rendered Markdown output to ensure it renders correctly and follows the template markdown style guide.
  • The template guide title is present and is an H1.
  • The template includes an introductory comment pointing them to other template resources.
  • Embedded writing tips are formatted with {curly brackets}.
  • The template guide is free from grammar errors and typos.
  • The template guide includes a "Why do I need this type of document?" section.
  • The template guide includes a "Contents of this template" section.
  • The contents listed in the "Contents of this template" section mirror the sections in the raw template.
  • The template guide includes an implementation checklist (optional).
  • The template guide includes additional resources (optional).
  • The template guide is well-organized and the contents flow in a logical order.
  • The template guide is well-written, clear, and provides sound advice to template users.

Deep dive requirements (optional) - PULL REQUEST REVIEWER ONLY

  • Check rendered Markdown output to ensure it renders correctly and follows the template markdown style guide.
  • The deep drive title is present and is an H1.
  • The deep dive guide provides helpful advice about necessary requirements for writing this type of documentation.
  • The template set is well-organized and the contents flow in a logical order.
  • The template is well-written and clear.

Template example requirements (optional) - PULL REQUEST REVIEWER ONLY

  • Check rendered Markdown output to ensure it renders correctly and follows the template markdown style guide.
  • The template example provided is well-written and provides a clear example of how to use the template.

@flicstar flicstar self-assigned this May 17, 2022
Copy link
Contributor

@flicstar flicstar left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall, a really great doc set. I can see the huge amount of work that has gone into this. Nice work team!

  • I have made comments and suggestions on each file.
  • Because this is a docset, I completed the PR reviewer checklist for each document (tracking in a separate spreadsheet).
  • I am new to ConventionalComments so please forgive when I forgot to use them.

I reviewed them in the order of:

  1. CoC
  2. Incident record
  3. Remediation record
  4. Response plan.

It might help you to address the comments in that order, too.

* A supplementary `code-of-conduct-guide.md` that provides more detailed information about using this template. Read the guide document first!
* The Code of Conduct template should be used along with several other templates, including:
* A `template-code-of-conduct-response.md` file that you can use to create and explain the policy your team will follow as you handle Code of Conduct incidents. This template is included in the same folder as the Code of Conduct template.
* A `template-code-of-conduct-incident-record.md` file for a form that is filled out when a community moderator takes an incident report from a community members. This template is included in the same folder as the Code of Conduct template.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* A `template-code-of-conduct-incident-record.md` file for a form that is filled out when a community moderator takes an incident report from a community members. This template is included in the same folder as the Code of Conduct template.
* A `template-code-of-conduct-incident-record.md` file for a form that is filled out when a community moderator takes an incident report from a community member. This template is included in the same folder as the Code of Conduct template.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, Felicity. I'm going to adopt your suggestion here, but I'm not going to commit it because it tends to cause problems for me.

* A supplementary `code-of-conduct-guide.md` that provides more detailed information about using this template. Read the guide document first!
* The Code of Conduct template should be used along with several other templates, including:
* A `template-code-of-conduct-response.md` file that you can use to create and explain the policy your team will follow as you handle Code of Conduct incidents. This template is included in the same folder as the Code of Conduct template.
* A `template-code-of-conduct-incident-record.md` file for a form that is filled out when a community moderator takes an incident report from a community members. This template is included in the same folder as the Code of Conduct template.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion (polish): Change 'file for a form'
Just a suggestion to keep this parallel with the previous construction ("that you can use"), we could change this to something like "... file. This is a form the community moderator can use when..."

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've adopted this suggestion and I've rewritten this section a little bit to add a little bit more clarity around the file names.

---

{Include your project's opening statement of purpose in this section.
You can use this boilerplate text and replace your own project's name in the indicated placeholder text.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
You can use this boilerplate text and replace your own project's name in the indicated placeholder text.
Replace your own project's name in the indicated placeholder text.

Suggestion (non-blocking)
Only because it seems repetitive when you read the next sentence.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've adopted this suggestion, but I didn't commit it because I don't like to commit suggestions. It causes rebasing problems for me.

Comment on lines +26 to +27
This includes everyone, regardless of: ability, age, background, body size or type, caste, disability (either visible or invisible), education, ethnicity, family status, gender, gender identity and expression, geographic location, level of
experience, marital status, nationality or national origin, native language, personal appearance, race, religion, sexual identity and orientation, socio-economic status, or any other dimension of diversity.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Praise: love this long list, and how it's alphabetical! ♥

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Praise: So well thought through list!

We expect our members, contributors, and leaders to:

- Participate in the community actively and authentically. Your meaningful contributions add to the health and longevity of this community.
- When you make commitments to other members of the project, do your best to keep those commitments. Other community members will trust you and build confidence in you if you fulfill your promises. If something may prevent you from keeping a commitment or if you discover you won't be able to complete a task on time, try to notify others as soon as possible.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- When you make commitments to other members of the project, do your best to keep those commitments. Other community members will trust you and build confidence in you if you fulfill your promises. If something may prevent you from keeping a commitment or if you discover you won't be able to complete a task on time, try to notify others as soon as possible.
- When you make commitments, do your best to keep those commitments. Other community members will trust you and build confidence in you if you fulfill your promises. If something may prevent you from keeping a commitment or if you discover you won't be able to complete a task on time, try to notify others as soon as possible.

suggestion (logic): I stumbled on this when reading. Am I always making comitments to members? I think it's the "to". Maybe I'm comitting to a task. ? Anyway, I think it stands if we remove this phrase. And bonus, we cut word count.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've adopted this suggestion, but I didn't commit it.

- If there are other resources that we are not aware of, please (open an issue)[https://github.com/thegooddocsproject/templates/issues] to let us know!

In addition to these resources, we recommend holding regular practice sessions with your community moderators where you role-play what it would be like to handle an actual incident if one were to occur.
Try creating a hypothetical situation and seeing if you can take it through the entire process to its conclusion.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Try creating a hypothetical situation and seeing if you can take it through the entire process to its conclusion.
Try creating a hypothetical situation and see if you can take it through the entire process to its conclusion.

suggestion

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adopted.


### About the "Reviewing the Code of Conduct" section

In the *Reviewing the Code of Conduct* section, indicate your timetable for reviewing the Code of Conduct and supporting policy documents.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

query: sometimes we say "In this section" and sometimes we put the name in italics. Is there a style? We should be consistent throughout the document set. I'm in two minds about which one I prefer.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And here I thought that I was avoiding monotony by changing it up from time to time. :)

It makes up the main body of this document and explains how you will handle incident reports.

The remediation process explained in this template was based on the Mozilla process for handling incidents.
You can feel free to adapt the process for your community if needed.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
You can feel free to adapt the process for your community if needed.
Feel free to adapt the process for your community if needed.

suggestion.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adopted.


The *Resolve* section explains how to conclude the Code of Conduct investigation by filing the necessary paperwork for record-keeping purposes.

It is important to file this documentation to enable the community moderators to identify and prevent potential repeated patterns of abuse in the community.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here's this use of "file" again. I tripped over it a few times in this document set, but I have commented in those other places.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changed to "record and store."

- [Mozilla's Community Participation Guidelines Enforcement](https://mozilla.teachable.com/p/cpg-training-contributors)
- [Otter Tech Code of Conduct Enforcement Training](https://otter.technology/code-of-conduct-training/)

Once again, if there are other resources that we are not aware of, please (open an issue)[https://github.com/thegooddocsproject/templates/issues] to let us know!
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Once again, if there are other resources that we are not aware of, please (open an issue)[https://github.com/thegooddocsproject/templates/issues] to let us know!
Once again, if there are other resources that we are not aware of, please [open an issue](https://github.com/thegooddocsproject/templates/issues) to let us know!

suggestion: correct link syntax

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adopted.

Escrowed reports will not be acted upon until there is a second report of the same incident or a similar incident involving the same individual.
The goal of an escrow report is to retain a record of incidents in case there is a pattern of misbehavior by the same individual.

If the reporter wishes to keep the report in escrow, the incident record should still be filled out and filed in the appropriate archives for future tracking.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If the reporter wishes to keep the report in escrow, the incident record should still be filled out and filed in the appropriate archives for future tracking.
If the reporter wants to keep the report in escrow, the incident record should still be filled out and filed in the appropriate archives for future tracking.

suggestion: change wishes to wants. Subjective - I will raise as a style guide decision.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adopted.

* **Preparation** - Simply tell the community member beforehand that you wish to discuss an issue privately. Invite one other community moderator for support if needed.
* **Calmness** - When explaining what behavior prompted to Code of Conduct investigation, calmly state what the behavior was without judgment or emotion. State the impact on the incident reporter or the community.
* **Clarity** - Set a clear behavior modification plan. If possible, get the community member to agree to this plan.
* **Privacy** - Do not disclose the identity of the incident reporter or allow them to be contacted. If the community member under investigation wishes to contact the incident reporter to apologize, explain that you can take the apology on their behalf. With your permission, a public apology may be acceptable under the circumstances.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* **Privacy** - Do not disclose the identity of the incident reporter or allow them to be contacted. If the community member under investigation wishes to contact the incident reporter to apologize, explain that you can take the apology on their behalf. With your permission, a public apology may be acceptable under the circumstances.
* **Privacy** - Do not disclose the identity of the incident reporter or allow them to be contacted. If the community member under investigation wants to contact the incident reporter to apologize, explain that you can take the apology on their behalf. With your permission, a public apology may be acceptable under the circumstances.

suggestion

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adopted.


* Placeholder text that you can replace with your own text. This text is indicated in {curly braces}.
* Writing instructions, also in {curly braces}.
* A supplementary `code-of-conduct-guide.md` that provides more detailed information about using this template. Read the guide document first!
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

todo: As @flicstar pointed out earlier code-of-conduct-guide.md should be replaced with guide-code-of-conduct.md.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I've standardized them all now, so we should be good.


## Consequences of unacceptable behavior

Unacceptable behavior from any {Project name} community member, contributor, sponsors, or leaders will not be tolerated.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: Can we remove {Project name}? I just tried replacing it with an actual project name and it didn't sound right to me.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmmm... It doesn't sound right to you? It sounds right to me:

"Unacceptable behavior from any Salt Project community member..."

"Unacceptable behavior from any Good Docs Project community member..."

Can you tell me more about what doesn't sound right to you?

Unacceptable behavior from any {Project name} community member, contributor, sponsors, or leaders will not be tolerated.
We expect everyone to comply with requests to stop unacceptable behavior immediately.

If a community member engages in unacceptable behavior, any community member or moderator should report the incident to the {Project name} {link to your community moderators document [community moderators](../our-team/template-our_team.md)}.
Copy link
Contributor

@gayathri-krishnaswamy gayathri-krishnaswamy Jul 7, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: At the top we say that unacceptable behavior from any community member, sponsor, leader, etc. will not be tolerated. Going by the same logic, can we change the next point to?
If anyone in the community engages in unacceptable behavior, any community member or contributor can report the incident.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good. Adopted.

- Help you define and clearly communicate your organization's mission, values, and guiding principles.
- Encourage members of your community to behave ethically and inclusively.
- Make your community a better place to collaborate and work.
- Demonstrate to prospective community members that your community is one that is welcoming and safe to join.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nitpick: Can we rephrase it as? Demonstrate to prospective community members that your community is warm, welcoming, and safe to join.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure! I've adopted this suggestion.

@barbaricyawps
Copy link
Contributor Author

Thanks for your reviews, @flicstar and @gayathri-krishnaswamy . I've adopted most of your suggestions and pushed up the changes. Thank you!

Copy link
Contributor

@itsdeannat itsdeannat left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Echoing Felicity's comments that this is a great, thorough template set. I know other projects will find these templates and guides helpful for building their own communities.

My comments were mostly limited to polish, wording/phrasing, and link syntax. I seconded some of Felicity's comments, too. Let me know if you have any questions.

---
Thank you for downloading the Code of Conduct template from The Good Docs Project!
We welcome any kind of feedback on our templates, both positive and negative.
To suggest improvements, open an issue on our (https://github.com/thegooddocsproject/templates/issues)[Templates repository].
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
To suggest improvements, open an issue on our (https://github.com/thegooddocsproject/templates/issues)[Templates repository].
To suggest improvements, open an issue on our [https://github.com/thegooddocsproject/templates/issues](Templates repository).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, should have probably made this a good ol' fashioned comment, don't want to mess up commit history


The Code of Conduct template set includes:

* A Code of Conduct that you can use to create and explain your community's Code of Conduct. This template is included in the same folder as this template and is named `template-code-of-conduct.md`. See its accompany guide: `about-code-of-conduct.md`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion (polish): "accompanying?"

Or perhaps "see its template guide?" And this is in a few places


* A Code of Conduct that you can use to create and explain your community's Code of Conduct. This template is included in the same folder as this template and is named `template-code-of-conduct.md`. See its accompany guide: `about-code-of-conduct.md`.
* A Code of Conduct response plan template that you can use to create and explain the policy your team will follow as you handle Code of Conduct incidents. This template is included in the same folder as the Code of Conduct template and is named `template-code-of-conduct-response-plan.md`. See its accompany guide: `about-code-of-conduct-response-plan.md`.
* A Code of Conduct incident record template for a form that is filled out when a community moderator takes an incident report from a community member. This template is included in the same folder as the Code of Conduct template as the Code of Conduct template and is named `template-code-of-conduct-incident-record.md`. See its accompany guide: `about-code-of-conduct-incident-record.md`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion (polish): "This template is included in the same folder as the Code of Conduct template as the Code of Conduct template..."

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see that this chunk of text in reused in the other template guides, so I won't add more comments

### About the "Permission from incident reporter to proceed?" section

Ask the incident reporter for permission to proceeed.
Indicate their response in thise section.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion (typo): thise > this

The *Introduction* section includes a description of the goals the community moderator should keep in mind while taking an incident report from an individual.
The community moderator should refer to this section regularly to ensure that they stay focused on the goal of explaining the outcome of the Code of Conduct violation.
These meetings have the potential to be stressful and full of high emotions.
The introduction section provides some guidelines from keeping these meetings under control.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion (wording): Change to "...provides some guidelines for keeping these meetings under control"


Consider reviewing your Code of Conduct and your response plan on a yearly basis at least.
An annual review can also be a good time to check that each community moderator is familiar with your Code of Conduct policies and that they have been sufficiently trained in handling Code of Conduct incidents.
Ensure that someone in your community is responsible for ensuring the Code of Conduct is reviewed regularly.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion (phrasing): Could we say, "Ensure that someone in your community is responsible for regularly reviewing the Code of Conduct policies?"

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see this sentence also in about-code-of-conduct.md, too


## Why do I need a Code of Conduct incident record?

See the `guide-code-of-conduct.md` for reasons to incorporate a Code of Conduct and response plan.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

question: Should this be about-code-of-conduct.md?

TIPS FOR THE COMMUNITY MODERATOR:
When meeting with a community member to explain the outcome of a Code of Conduct violation, strive for these goals:

* **Preparation** - Simply tell the community member beforehand that you wish to discuss an issue privately. Invite one other community moderator for support if needed.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion (wording): one other > another (?)

{List the details of the behavioral modification plan as discussed with the other community moderators.


## Do you agree to follow the plan?
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure if this suggestion was adopted yet, but I second it

## Reviewing the Code of Conduct

The Code of Conduct and this document (the community moderators document) should be reviewed by the moderator team at least once a year, typically in {time period}, to ensure these documents are meeting the needs of the community.
The {Project name} community will notify the community of any revisions by publicizing the revisions in the community’s forums of communication on both Slack and the groups.io mailing list.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Second this suggestion if there's time to make it. Could be "and {other contact method}" or something similar?

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Code of Conduct template
4 participants