From 82662a1014586eba35d571aac16df44fe9f91849 Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 3 Jan 2024 13:16:19 +0100 Subject: [PATCH 01/25] feat: create effective-communication.md --- effective-communication.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 effective-communication.md diff --git a/effective-communication.md b/effective-communication.md new file mode 100644 index 0000000..e69de29 From b2cf8ad2e0876b0aecea157290046d2c6c0ea8f6 Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 3 Jan 2024 13:17:49 +0100 Subject: [PATCH 02/25] feat: add Effective Communication and Collaboration to sidebar --- _layouts/sidebar.md | 1 + 1 file changed, 1 insertion(+) diff --git a/_layouts/sidebar.md b/_layouts/sidebar.md index 4139cd4..cf5e587 100644 --- a/_layouts/sidebar.md +++ b/_layouts/sidebar.md @@ -1,3 +1,4 @@ - Pages - [What is an Open Source Maintainer?](/intro.md) - [Setting Up Your Project](/how-to-setup-your-project.md) + - [Effective Communication and Collaboration](/effective-communication.md) From ce86c5f0c6673a7f2f3af686d2072aa330344375 Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 3 Jan 2024 13:20:50 +0100 Subject: [PATCH 03/25] feat: add chapter 4 to README --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 3e0a746..cb26060 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,8 @@ The course is divided into X chapters, each covering a different aspect of being ### [Chapter 1: Setting Up Your Project](/how-to-setup-your-project.md) +### [Chapter 4: How to Create Effective Communication and Collaboration](/effective-communication.md) + ### Additional Information As this is the beginning of your open source maintainer journey, we've also provided additional information in these chapters: From 800adb3da3d99fdca4cb21cb6b6b713a8fbf81f0 Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 3 Jan 2024 13:21:17 +0100 Subject: [PATCH 04/25] feat: add intro paragraph --- effective-communication.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/effective-communication.md b/effective-communication.md index e69de29..b13a85b 100644 --- a/effective-communication.md +++ b/effective-communication.md @@ -0,0 +1,5 @@ +# How to Create Effective Communication and Collaboration + +Effective communication and collaboration with contributors are the keys to a thriving open source community. As maintainers, you want to smoothly onboard new contributors to your projects and build a welcoming community with open lines of communication between contributors and maintainers. + +In this section, we will discuss how to onboard new contributors, utilize different communication channels for your open source project's community, and maintain healthy communication. From 6d46f75c1cbcc71fd4779c431b63a31993a32bbc Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 3 Jan 2024 13:38:49 +0100 Subject: [PATCH 05/25] feat: add Project Onboarding section --- effective-communication.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/effective-communication.md b/effective-communication.md index b13a85b..b130447 100644 --- a/effective-communication.md +++ b/effective-communication.md @@ -3,3 +3,41 @@ Effective communication and collaboration with contributors are the keys to a thriving open source community. As maintainers, you want to smoothly onboard new contributors to your projects and build a welcoming community with open lines of communication between contributors and maintainers. In this section, we will discuss how to onboard new contributors, utilize different communication channels for your open source project's community, and maintain healthy communication. + +## Project Onboarding + +Onboarding new contributors to your project is important to maintaining its health and growth. And that will become possible through establishing effective communication, starting from your project's documentation. + +Providing clear information and directions about the project's goals, processes, and codebase is the key to helping new contributors collaborate. Effective communication allows you to attract contributors to return, learn more about your projects, and continue contributing. That way, you can create a sustainable ecosystem where knowledge is shared, responsibilities are distributed, and the project can continue to evolve and grow. + +There are some ways to establish effective communication on your project to achieve good collaboration. + +### Clear Documentation + +An easy to understand and well-organized documentation will ensure a good onboarding experience for new contributors. Clear documentation can save time, prevent errors, and promote transparency and accountability that can be vital for effective communication. So, it is best to invest time your time and effort in creating a clear documentation for your project. + +Consider these when you write or update your documentation: + +- **Use simple language and universal examples** + + You want to ensure that your documentation is easy to understand by most contributors — if not everyone — including non-native English speakers. + +- **Clear guide** + + Whether it's the setup guide on the README, instructions to run and use the project, or Contributing Guidelines, you always want to provide a clear direction for contributors to follow for better collaboration. + +- **A dedicated place for documentation** + + If your README is growing longer, consider creating a new file or repository dedicated to your project's documentation. This will ensure a good documentation flow, allowing you to communicate your project better. + +### Labeled Issues + +Labeling issues is an excellent way to categorize and communicate the status of issues in your project. It can also be a way to create contributors' paths. + +The `good first issue` label is perfect to be added to beginners-friendly issues. Think of contributors who are beginners in the tech stack or open source in general. It can be a good starting point for them to contribute to your project. These issues, in particular, should be well-documented and approachable. + +If an issue is complicated and has to be fixed promptly, you can add `core team work`, `critical`, or any other label based on your project's convention to prevent frustrations and confusion. + +### Issues and Pull Request Templates + +Having issues and pull request templates in your project makes it easier for you to triage and review them and helps contributors understand how to approach the project and what you expect them to look closer at when creating one. From 286b7e8269817c06983ec66f851579b0132a4fe5 Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 3 Jan 2024 13:57:48 +0100 Subject: [PATCH 06/25] fix: wording --- effective-communication.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/effective-communication.md b/effective-communication.md index b130447..8d856f1 100644 --- a/effective-communication.md +++ b/effective-communication.md @@ -14,7 +14,7 @@ There are some ways to establish effective communication on your project to achi ### Clear Documentation -An easy to understand and well-organized documentation will ensure a good onboarding experience for new contributors. Clear documentation can save time, prevent errors, and promote transparency and accountability that can be vital for effective communication. So, it is best to invest time your time and effort in creating a clear documentation for your project. +An easy-to-understand and well-organized documentation will ensure a good onboarding experience for new contributors. Clear documentation can save time, prevent errors, and promote transparency and accountability, which can be vital for effective communication. It is best to invest time and effort in creating clear documentation for your project. Consider these when you write or update your documentation: @@ -30,11 +30,11 @@ Consider these when you write or update your documentation: If your README is growing longer, consider creating a new file or repository dedicated to your project's documentation. This will ensure a good documentation flow, allowing you to communicate your project better. -### Labeled Issues +### Issue Labels Labeling issues is an excellent way to categorize and communicate the status of issues in your project. It can also be a way to create contributors' paths. -The `good first issue` label is perfect to be added to beginners-friendly issues. Think of contributors who are beginners in the tech stack or open source in general. It can be a good starting point for them to contribute to your project. These issues, in particular, should be well-documented and approachable. +The `good first issue` label is perfect to be added to beginners-friendly issues. Think of contributors who are beginners in the tech stack or open source in general. It can be a good starting point for them to contribute to your project. Consider pointing to the code blocks and providing step-by-step instructions to work on the solutions for this type of issue. If an issue is complicated and has to be fixed promptly, you can add `core team work`, `critical`, or any other label based on your project's convention to prevent frustrations and confusion. From fde9047fda48200eff46a31aa416fc31219bbd96 Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 3 Jan 2024 17:28:51 +0100 Subject: [PATCH 07/25] feat: add Regular Communication section --- effective-communication.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/effective-communication.md b/effective-communication.md index 8d856f1..f8403c0 100644 --- a/effective-communication.md +++ b/effective-communication.md @@ -41,3 +41,33 @@ If an issue is complicated and has to be fixed promptly, you can add `core team ### Issues and Pull Request Templates Having issues and pull request templates in your project makes it easier for you to triage and review them and helps contributors understand how to approach the project and what you expect them to look closer at when creating one. + +## Regular Communication + +Providing spaces outside your project for contributors to ask questions, request guidance, and give ideas is recommended. That way, they can communicate and collaborate actively with other collaborators and maintainers. + +Here are some channels for you to consider to create regular communication: + +### GitHub Discussions + +[Discussions](https://github.com/features/discussions) is a collaborative communication forum for the community around an open source project. It's a feature on GitHub to ask questions, share ideas, and build connections with each other. You can easily enable discussions in your project by following the [complete instructions](https://docs.github.com/en/discussions/quickstart#enabling-github-discussions-on-your-repository). + +### Discord Community + +> [Discord](https://discord.com/) is a voice, video and text communication service used by over a hundred million people to hang out and talk with their friends and communities. + +You can create a community around your project and gather them in Discord. Besides allowing contributors to ask questions, connect, and collaborate in nearly real-time, it can also benefit you. You can announce project updates, ask for help, hold sync office hours to talk about your projects and know your contributors better, and many more. + +### Slack Group + +Like Discord, [Slack](https://slack.com/) provides a platform for your community to chat, connect, and collaborate. + +You can automate tasks like scheduling announcements and integrating software and custom apps right into Slack — for example, connecting Slack to a [Zoom](https://zoom.us/) meeting room, etc. + +Which one to choose — Slack or Discord — is based on your preference and the needs of your community. + +### Community Forum + +Another place to create a communication space is a forum. A community forum is an online space where community members connect, engage, and discuss topics with each other. + +You can create and host a forum on a website. Or, you can make it a subdomain of your website. Take [freeCodeCamp forum](https://forum.freecodecamp.org/) as an example for inspiration. From b241aad5b263699a489c384d9bc5b09f28bc4e7b Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Fri, 5 Jan 2024 21:27:11 +0100 Subject: [PATCH 08/25] add: Effective Communication and Engaging with Contributors sections --- effective-communication.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/effective-communication.md b/effective-communication.md index f8403c0..c3526be 100644 --- a/effective-communication.md +++ b/effective-communication.md @@ -71,3 +71,19 @@ Which one to choose — Slack or Discord — is based on your preference and the Another place to create a communication space is a forum. A community forum is an online space where community members connect, engage, and discuss topics with each other. You can create and host a forum on a website. Or, you can make it a subdomain of your website. Take [freeCodeCamp forum](https://forum.freecodecamp.org/) as an example for inspiration. + +## Effective Communication + +Effective communication is key to project success. It plays a vital role in resolving issues, building trust and transparency, and encouraging collaboration. By enabling open and healthy communication, you can ensure everyone is on the same page and working towards a common goal. + +### Engaging with Contributors + +Having contributors come back and continue contributing to the project is one of the maintainers' goals. To nurture this relationship, you should have time to engage with your contributors between tasks. + +Start by acknowledging and thanking them for the issue or pull request they created. Ask them questions if something is not clear enough for you. Keep your message clear and short so they can understand your purpose. When you deliver a few topics, using bullet points in a comment or splitting your message into several comments is recommended. + +One of the golden rules in an international remote environment is never to make an assumption. Async communication, more often than not, can lead to misunderstanding because writing is different from speaking. People with different cultural and language backgrounds might need help explaining their intentions or understanding specific cultural sayings. Consider using words with explicit meanings when you are communicating. + +Another way to engage with your contributors is by holding a regular office hour. In sync, you can hear their ideas and challenges, communicate with them about your project's direction, and more. This can be a good way to get to know your contributors closer and vice versa. + +Maintainers are human. Sometimes, when you're tired or having a bad day, a discussion with a contributor can upset you. Remember that you always want to foster a healthy communication and welcoming environment. It's okay to wait to answer them. You can take a couple of hours or even a day before you return to them to avoid a bitter tone. From 935546648cd2a89141ae313aa57f039d74189f9e Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Fri, 5 Jan 2024 21:44:13 +0100 Subject: [PATCH 09/25] docs: add Managing Expectations section --- effective-communication.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/effective-communication.md b/effective-communication.md index c3526be..7c4d35b 100644 --- a/effective-communication.md +++ b/effective-communication.md @@ -87,3 +87,25 @@ One of the golden rules in an international remote environment is never to make Another way to engage with your contributors is by holding a regular office hour. In sync, you can hear their ideas and challenges, communicate with them about your project's direction, and more. This can be a good way to get to know your contributors closer and vice versa. Maintainers are human. Sometimes, when you're tired or having a bad day, a discussion with a contributor can upset you. Remember that you always want to foster a healthy communication and welcoming environment. It's okay to wait to answer them. You can take a couple of hours or even a day before you return to them to avoid a bitter tone. + +### Managing Expectations + +The earlier you let contributors know what they can expect from you and what you expect from them, the better. Setting and managing expectations is the key to smooth contributions and project management. + +Here are some ways to help you manage expectations: + +- **Small issues**: + + Just like maintainers, most open source contributors are volunteers. They are not required to, but they help you fix and enhance your project in their spare time. So you can't expect them to work on their issues promptly like a regular employee. With this expectation, you can, for example, break your issues into several small ones to prevent them from taking a long time to work on an issue. + +- **Styling guide** + + You might prefer contributors to add a prefix to issue, pull request titles, and their commit messages. Or you might select particular Markdown rules for your project. Every project has its own convention. Don't expect your contributors to know what to do when contributing to your project. Consider communicating this in a clear guide they must follow. + +- **Support** + + What kind of support can you provide, and where can they reach you? Think of answering questions, pair programming, or office hours, for example, on Discord. To inform this, you can add a section in your README or Contributing Guide. + +- **Timeline** + + You can let your contributors know how long they can expect you to review a pull request or to answer their questions. Inform them if you, for example, won't be available on weekends or after working hours. From dfd0730e42559d66f015435d237789cd594c86d9 Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Tue, 9 Jan 2024 13:02:31 +0100 Subject: [PATCH 10/25] docs: add Boundaries point to Managing Expectations section --- effective-communication.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/effective-communication.md b/effective-communication.md index 7c4d35b..78b683b 100644 --- a/effective-communication.md +++ b/effective-communication.md @@ -109,3 +109,23 @@ Here are some ways to help you manage expectations: - **Timeline** You can let your contributors know how long they can expect you to review a pull request or to answer their questions. Inform them if you, for example, won't be available on weekends or after working hours. + +- **Boundaries** + + As your project grows and gains popularity, it will attract more contributors. Creating and setting clear boundaries becomes essential to prevent you from getting burned out quickly and balance your life. + + - **Take a Break** + + You need to know that it's okay to take time off, step away from your project, and take care of yourself. You can inform your contributors that you will review their pull requests after you return. Here is an example of what you can say: + + > "Hey {username}, thank you for your PR. I will take two weeks off starting tomorrow and review this upon my return. You may ask about the status of your PR if I haven't responded to it in the next three weeks." + + When pull requests come during your days off, you can apologize and thank them for their patience after you return. Consider to say something like this: + + > "Hey {username}, I apologize for the late response, as I just got back from my days off. Thank you for taking on this! I need time to review it and will get back to you soon. I appreciate your patience." + + - **No Private Message** + + Another boundary you can set is for contributors not to send you private messages on chat service apps like Discord or social media. + + The culture of open source is open communication and transparency. It is best to keep all contributors in the loop by communicating anything related to the project in the open so everyone knows what's happening and what to expect. It will also give you the necessary privacy, separating your project from your personal life. From 544bba238c869c7218567fb0b23b8cb04e956ca9 Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 10 Jan 2024 10:40:55 +0100 Subject: [PATCH 11/25] docs: add Handling Difficult Situations section --- effective-communication.md | 59 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/effective-communication.md b/effective-communication.md index 78b683b..1ee4614 100644 --- a/effective-communication.md +++ b/effective-communication.md @@ -129,3 +129,62 @@ Here are some ways to help you manage expectations: Another boundary you can set is for contributors not to send you private messages on chat service apps like Discord or social media. The culture of open source is open communication and transparency. It is best to keep all contributors in the loop by communicating anything related to the project in the open so everyone knows what's happening and what to expect. It will also give you the necessary privacy, separating your project from your personal life. + +### Handling Difficult Situations + +You might need to handle difficult situations or resolve conflicts around your project's community one day. There is no easy way to handle situations like this. But sooner or later, you need to prepare yourself. + +Here are essential things to do when handling difficult situations: + +#### Active Listening + +Active listening plays an important role in handling a difficult situation. You can only resolve a problem if you understand it clearly. + +Active listening is a communication skill to not only hear the words of a speaker but also try to understand their intentions completely and acknowledge their feelings. + +Here are some techniques that you can train for active listening: + +- **Being fully present** + + Avoid listening to someone talking while preparing your answer. Doing so will distract you and make you miss something they've said, which can cause you to fail to understand the exact intention. + +- **Showing interest** + + If it's a sync conversation, use eye contact to show your interest in what the speaker is saying. In an async conversation, you can repeat what they are saying in your own words based on your understanding. It will show them that you are interested in their conversation. And they can correct you if you need help understanding it clearly. + +- **Acknowledging emotions** + + You want to be able to recognize and acknowledge the speaker's feelings in sync or async conversations. For example, you can say, "I see that it upsets you," or, "I'm excited for you!" when the speaker uses many exclamations in their writing. + +- **Asking and clarifying** + + When someone feels many emotions, they usually want to talk and let the feeling out fast. That can result in a lack of information or the inability to think of more suitable words to describe the situation. You always want to gain more information and clarify what is said. For example, "You said they contacted you on Monday [_clarifying_]. Did they file the complaint on the same day? [_asking for more information_]" + +#### Having Empathy and Compassion + +It would be best to be emphatic and compassionate when handling a problem, for example, when you face a dispute between contributors or community members. + +You must look at and listen to the problem from both sides to keep yourself non-judgemental. Then, put yourself in their shoes to see the case from their perspective to understand it better. Empathy and compassion will help you not only resolve a conflict but also create a positive environment. + +#### Being Tactful and Diplomatic + +A critical factor in successfully addressing a problem is to approach it in a way that values and respects the feelings and perspectives of others. This not only prevents any harm to the relationship but also leads to positive outcomes when resolving conflicts. + +The key is to think before you speak and choose your words wisely. You want to be able to tell the truth, but at the same time, also consider others' feelings and make them feel safe. Use positive language, yet direct, to prevent misunderstandings. You should consider balancing being straightforward and sensitive and avoid pointing fingers. + +**Here is an example of a scenario**: + +You have a contributor who contributes multiple times and has been working fast to deliver their code. But when you review their pull request and test their branch locally, it works differently than you intended. You know they often don't understand the issue, but they assume they do. And you also notice that they rarely run the code locally to test it. You keep giving them support and positive feedback until, one day, you can't take it anymore. + +Instead of saying: + +> "Hey, why do you always deliver the code that doesn't align with what we want? I notice you've done this so many times. Do you even understand the issues? I'm also not sure if you ever run your code locally because it often doesn't work the way it should and, worst, breaks the app." + +You can say something like: + +> "Thank you for your prompt work on the PRs, {username}. I really appreciate it! However, let's focus more on quality than quantity. I noticed a few things that I believe could further improve the quality of your work: +> +> - It might be a good idea to take time to fully understand the issue before starting work on a PR, as this solution is different from what we asked in the issue. If you need help or clarification, don't hesitate to reach out. +> - Another thing that could be helpful is running and testing the code locally before submitting a PR. This way, you'll be able to ensure that the code runs as it should. It can save you time from going back and forth on revisions. +> +> I hope you find this feedback helpful. If there's anything I can do to support you, please let me know. From 12797d6dfc8d27cd15e30dfb849e5b8087155b44 Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 10 Jan 2024 14:57:59 +0100 Subject: [PATCH 12/25] docs: improve Regular Communication section --- effective-communication.md | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/effective-communication.md b/effective-communication.md index 1ee4614..3bbf19f 100644 --- a/effective-communication.md +++ b/effective-communication.md @@ -48,28 +48,36 @@ Providing spaces outside your project for contributors to ask questions, request Here are some channels for you to consider to create regular communication: -### GitHub Discussions +### Chat Service App + +You can accommodate sync communication for your community by providing a chat service app. Besides having one allowing contributors to ask questions, connect, and collaborate openly in real-time, it can also benefit you as a maintainer. You can quickly announce project updates, ask for help, hold sync office hours to talk about your projects and know your contributors better, and many more. -[Discussions](https://github.com/features/discussions) is a collaborative communication forum for the community around an open source project. It's a feature on GitHub to ask questions, share ideas, and build connections with each other. You can easily enable discussions in your project by following the [complete instructions](https://docs.github.com/en/discussions/quickstart#enabling-github-discussions-on-your-repository). +Tech communities widely use the apps mentioned here. But which one to choose is based on your preference and the needs of your community. -### Discord Community +#### Discord Community > [Discord](https://discord.com/) is a voice, video and text communication service used by over a hundred million people to hang out and talk with their friends and communities. -You can create a community around your project and gather them in Discord. Besides allowing contributors to ask questions, connect, and collaborate in nearly real-time, it can also benefit you. You can announce project updates, ask for help, hold sync office hours to talk about your projects and know your contributors better, and many more. +The Discord market mainly targets gamers. It is a good choice if your community heavily uses group voice and video calls. Creating a channel for voice calls makes it easy for community members to join the channel and talk to anyone instantly. Discord is also suitable for building a larger community because if your server is public, anyone with a Discord account can search and join your group. + +#### Slack Group -### Slack Group +> [Slack](https://slack.com/) is the productivity platform that empowers everyone with no-code automation and AI, makes search and knowledge sharing seamless, and keeps teams connected and engaged. -Like Discord, [Slack](https://slack.com/) provides a platform for your community to chat, connect, and collaborate. +Slack primarily targets businesses and professional teams. That said, if your community prioritizes using chat more than voice or video calls, Slack can accommodate this through its simple and intuitive interface and ability to organize conversations. Slack can automate workflow and be integrated with thousands of business applications, including Zoom and GitHub. -You can automate tasks like scheduling announcements and integrating software and custom apps right into Slack — for example, connecting Slack to a [Zoom](https://zoom.us/) meeting room, etc. +### GitHub Discussions + +[Discussions](https://github.com/features/discussions) is a collaborative communication forum for the community around an open source project. It's a feature on GitHub to ask questions, share ideas, and build connections with each other around the project. -Which one to choose — Slack or Discord — is based on your preference and the needs of your community. +You can easily enable discussions in your project by following the [complete instructions](https://docs.github.com/en/discussions/quickstart#enabling-github-discussions-on-your-repository). ### Community Forum Another place to create a communication space is a forum. A community forum is an online space where community members connect, engage, and discuss topics with each other. +One of the benefits of having a community forum is a place for members to discuss and ask specific questions about your project. Whenever someone encounters the same problem that has been fixed before, they can fix it faster by searching for the solutions on the forum. This can increase the productivity of maintainers because you don't have to answer the same questions repeatedly. A forum is also available publicly, so it's searchable on search engines and can increase the number of users and contributors. + You can create and host a forum on a website. Or, you can make it a subdomain of your website. Take [freeCodeCamp forum](https://forum.freecodecamp.org/) as an example for inspiration. ## Effective Communication From 6407f05a729b85f418c65bb31484010793d5b80b Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 10 Jan 2024 17:29:34 +0100 Subject: [PATCH 13/25] docs: improve Managing Expectations section --- effective-communication.md | 44 +++++++++++++++++++++----------------- 1 file changed, 24 insertions(+), 20 deletions(-) diff --git a/effective-communication.md b/effective-communication.md index 3bbf19f..1564cce 100644 --- a/effective-communication.md +++ b/effective-communication.md @@ -98,45 +98,49 @@ Maintainers are human. Sometimes, when you're tired or having a bad day, a discu ### Managing Expectations -The earlier you let contributors know what they can expect from you and what you expect from them, the better. Setting and managing expectations is the key to smooth contributions and project management. +The earlier you let contributors know what they can expect from you and what you expect from them, the better. Setting and managing expectations is the key to smooth contributions and project management. So, how can you manage and communicate your expectations? -Here are some ways to help you manage expectations: +#### Small Issues -- **Small issues**: +Just like maintainers, most open source contributors are volunteers. They are not required to, but they help you fix and enhance your project in their spare time. So you can't expect them to work on their issues promptly like a regular employee. With this expectation, you can, for example, break your issues into several small ones to prevent them from taking a long time to work on an issue. - Just like maintainers, most open source contributors are volunteers. They are not required to, but they help you fix and enhance your project in their spare time. So you can't expect them to work on their issues promptly like a regular employee. With this expectation, you can, for example, break your issues into several small ones to prevent them from taking a long time to work on an issue. +#### Styling Guide -- **Styling guide** +You might prefer contributors to add a prefix to issue, pull request titles, and their commit messages. Or you might select particular Markdown rules for your project. Every project has its own convention. So, don't expect your contributors to know what to do when contributing to your project. Consider communicating this in a clear styling guide they must follow. - You might prefer contributors to add a prefix to issue, pull request titles, and their commit messages. Or you might select particular Markdown rules for your project. Every project has its own convention. Don't expect your contributors to know what to do when contributing to your project. Consider communicating this in a clear guide they must follow. +#### Support -- **Support** +What kind of support can you provide for your contributors? Where can they reach you? You can think of these amongst other supports: - What kind of support can you provide, and where can they reach you? Think of answering questions, pair programming, or office hours, for example, on Discord. To inform this, you can add a section in your README or Contributing Guide. +- Where can contributors ask questions? +- Can you give them support in pair programming when necessary? How can contributors ask for one? +- Will you hold office hours? If so, would it be regular or based on request? Where will it happen, and how will you announce it? -- **Timeline** +You can add a section in your README or Contributing Guide to inform about the support you can give. - You can let your contributors know how long they can expect you to review a pull request or to answer their questions. Inform them if you, for example, won't be available on weekends or after working hours. +#### Timeline -- **Boundaries** +Let your contributors know how long they can expect you to review a pull request or to answer their questions. Inform them if you, for example, won't be available on weekends or after working hours. - As your project grows and gains popularity, it will attract more contributors. Creating and setting clear boundaries becomes essential to prevent you from getting burned out quickly and balance your life. +#### Boundaries - - **Take a Break** +As your project grows and gains popularity, it will attract more contributors. Creating and setting clear boundaries becomes essential to prevent you from getting burned out quickly and balance your life. Here are some ways to create boundaries: - You need to know that it's okay to take time off, step away from your project, and take care of yourself. You can inform your contributors that you will review their pull requests after you return. Here is an example of what you can say: +- **Take a Break** - > "Hey {username}, thank you for your PR. I will take two weeks off starting tomorrow and review this upon my return. You may ask about the status of your PR if I haven't responded to it in the next three weeks." + You need to know that it's okay to take time off, step away from your project, and take care of yourself. You can inform your contributors that you will review their pull requests after you return. Here is an example of what you can say: - When pull requests come during your days off, you can apologize and thank them for their patience after you return. Consider to say something like this: + > "Hey {username}, thank you for your PR. I will take two weeks off starting tomorrow and review this upon my return. You may ask about the status of your PR if I haven't responded to it in the next three weeks." - > "Hey {username}, I apologize for the late response, as I just got back from my days off. Thank you for taking on this! I need time to review it and will get back to you soon. I appreciate your patience." + When pull requests come during your days off, you can apologize and thank them for their patience after you return. Consider to say something like this: - - **No Private Message** + > "Hey {username}, I apologize for the late response, as I just got back from my days off. Thank you for taking on this! I need time to review it and will get back to you soon. I appreciate your patience." - Another boundary you can set is for contributors not to send you private messages on chat service apps like Discord or social media. +- **No Private Message** - The culture of open source is open communication and transparency. It is best to keep all contributors in the loop by communicating anything related to the project in the open so everyone knows what's happening and what to expect. It will also give you the necessary privacy, separating your project from your personal life. + Another boundary you can set is for contributors not to send you private messages on chat service apps like Discord or social media. + + The culture of open source is open communication and transparency. It is best to keep all contributors in the loop by communicating anything related to the project in the open so everyone knows what's happening and what to expect. It will also give you the necessary privacy, separating your project from your personal life. ### Handling Difficult Situations From 319a0e7009d7846bd43ae41129e2b9d8ca1e6cb2 Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 10 Jan 2024 17:41:09 +0100 Subject: [PATCH 14/25] fix: adjust wording --- effective-communication.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/effective-communication.md b/effective-communication.md index 1564cce..10f4dd2 100644 --- a/effective-communication.md +++ b/effective-communication.md @@ -10,7 +10,7 @@ Onboarding new contributors to your project is important to maintaining its heal Providing clear information and directions about the project's goals, processes, and codebase is the key to helping new contributors collaborate. Effective communication allows you to attract contributors to return, learn more about your projects, and continue contributing. That way, you can create a sustainable ecosystem where knowledge is shared, responsibilities are distributed, and the project can continue to evolve and grow. -There are some ways to establish effective communication on your project to achieve good collaboration. +There are ways to establish effective communication on your project to achieve good collaboration. ### Clear Documentation @@ -18,7 +18,7 @@ An easy-to-understand and well-organized documentation will ensure a good onboar Consider these when you write or update your documentation: -- **Use simple language and universal examples** +- **Simple language and universal examples** You want to ensure that your documentation is easy to understand by most contributors — if not everyone — including non-native English speakers. @@ -26,7 +26,7 @@ Consider these when you write or update your documentation: Whether it's the setup guide on the README, instructions to run and use the project, or Contributing Guidelines, you always want to provide a clear direction for contributors to follow for better collaboration. -- **A dedicated place for documentation** +- **Dedicated place for documentation** If your README is growing longer, consider creating a new file or repository dedicated to your project's documentation. This will ensure a good documentation flow, allowing you to communicate your project better. @@ -78,7 +78,7 @@ Another place to create a communication space is a forum. A community forum is a One of the benefits of having a community forum is a place for members to discuss and ask specific questions about your project. Whenever someone encounters the same problem that has been fixed before, they can fix it faster by searching for the solutions on the forum. This can increase the productivity of maintainers because you don't have to answer the same questions repeatedly. A forum is also available publicly, so it's searchable on search engines and can increase the number of users and contributors. -You can create and host a forum on a website. Or, you can make it a subdomain of your website. Take [freeCodeCamp forum](https://forum.freecodecamp.org/) as an example for inspiration. +You can create and host a forum on a website. Or, you can make it a subdomain of your website. Take the [freeCodeCamp forum](https://forum.freecodecamp.org/) as an example for inspiration. ## Effective Communication @@ -94,7 +94,7 @@ One of the golden rules in an international remote environment is never to make Another way to engage with your contributors is by holding a regular office hour. In sync, you can hear their ideas and challenges, communicate with them about your project's direction, and more. This can be a good way to get to know your contributors closer and vice versa. -Maintainers are human. Sometimes, when you're tired or having a bad day, a discussion with a contributor can upset you. Remember that you always want to foster a healthy communication and welcoming environment. It's okay to wait to answer them. You can take a couple of hours or even a day before you return to them to avoid a bitter tone. +Maintainers are human. Sometimes, a discussion with a contributor can upset you when you're tired or having a bad day. Always remember that you want to foster a healthy communication and welcoming environment. So, it's okay to cool down and take time to answer them. You can take a couple of hours or even a day before you return to them to avoid a bitter tone. ### Managing Expectations @@ -150,7 +150,7 @@ Here are essential things to do when handling difficult situations: #### Active Listening -Active listening plays an important role in handling a difficult situation. You can only resolve a problem if you understand it clearly. +Active listening plays a vital role in handling a difficult situation. You can only resolve a problem if you understand it clearly. Active listening is a communication skill to not only hear the words of a speaker but also try to understand their intentions completely and acknowledge their feelings. @@ -162,7 +162,7 @@ Here are some techniques that you can train for active listening: - **Showing interest** - If it's a sync conversation, use eye contact to show your interest in what the speaker is saying. In an async conversation, you can repeat what they are saying in your own words based on your understanding. It will show them that you are interested in their conversation. And they can correct you if you need help understanding it clearly. + If it's a sync conversation, use eye contact to show your interest in what the speaker is saying. In an async chat, you can repeat what they are saying in your own words based on your understanding. It will show them that you are interested in their conversation. And they can correct you if you need help understanding it clearly. - **Acknowledging emotions** @@ -182,7 +182,7 @@ You must look at and listen to the problem from both sides to keep yourself non- A critical factor in successfully addressing a problem is to approach it in a way that values and respects the feelings and perspectives of others. This not only prevents any harm to the relationship but also leads to positive outcomes when resolving conflicts. -The key is to think before you speak and choose your words wisely. You want to be able to tell the truth, but at the same time, also consider others' feelings and make them feel safe. Use positive language, yet direct, to prevent misunderstandings. You should consider balancing being straightforward and sensitive and avoid pointing fingers. +The key is to think before you speak and choose your words wisely. You want to be able to tell the truth, but at the same time, also consider others' feelings and make them feel safe. Use positive yet direct language to prevent misunderstandings; consider balancing being straightforward and sensitive, and avoid pointing fingers. **Here is an example of a scenario**: @@ -190,7 +190,7 @@ You have a contributor who contributes multiple times and has been working fast Instead of saying: -> "Hey, why do you always deliver the code that doesn't align with what we want? I notice you've done this so many times. Do you even understand the issues? I'm also not sure if you ever run your code locally because it often doesn't work the way it should and, worst, breaks the app." +> "Hey, why do you always deliver the code that doesn't align with what we want? I notice you've done this so many times. Do you even understand the issues? I'm also wondering if you ever run your code locally because it often doesn't work the way it should and, worst, breaks the app." You can say something like: From acfc661d0ee6e20e17f9ecab166a61bd426b630e Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Thu, 11 Jan 2024 11:34:26 +0100 Subject: [PATCH 15/25] fix: apply suggestions and minor wording adjustment --- effective-communication.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/effective-communication.md b/effective-communication.md index 10f4dd2..a5f1732 100644 --- a/effective-communication.md +++ b/effective-communication.md @@ -1,4 +1,4 @@ -# How to Create Effective Communication and Collaboration +# How to Effectively Communicate and Collaborate Effective communication and collaboration with contributors are the keys to a thriving open source community. As maintainers, you want to smoothly onboard new contributors to your projects and build a welcoming community with open lines of communication between contributors and maintainers. @@ -14,7 +14,7 @@ There are ways to establish effective communication on your project to achieve g ### Clear Documentation -An easy-to-understand and well-organized documentation will ensure a good onboarding experience for new contributors. Clear documentation can save time, prevent errors, and promote transparency and accountability, which can be vital for effective communication. It is best to invest time and effort in creating clear documentation for your project. +Easy-to-understand and well-organized documentation will ensure a good onboarding experience for new contributors. Clear documentation can save time, prevent errors, and promote transparency and accountability, which can be vital for effective communication. It is best to invest time and effort in creating clear documentation for your project. Consider these when you write or update your documentation: @@ -32,9 +32,9 @@ Consider these when you write or update your documentation: ### Issue Labels -Labeling issues is an excellent way to categorize and communicate the status of issues in your project. It can also be a way to create contributors' paths. +Labeling issues is an excellent way to categorize and communicate the status of issues in your project. It can also be a way to create contributors' paths. The [Issues and Pull Requests](/issues-and-pull-requests.md) chapter covers this topic more in-depth. -The `good first issue` label is perfect to be added to beginners-friendly issues. Think of contributors who are beginners in the tech stack or open source in general. It can be a good starting point for them to contribute to your project. Consider pointing to the code blocks and providing step-by-step instructions to work on the solutions for this type of issue. +The `good first issue` label is perfect to be added to beginner-friendly issues. Think of contributors who are beginners in the tech stack or open source in general. It can be a good starting point for them to contribute to your project. Consider pointing to the code blocks and providing step-by-step instructions to work on the solutions for this type of issue. If an issue is complicated and has to be fixed promptly, you can add `core team work`, `critical`, or any other label based on your project's convention to prevent frustrations and confusion. @@ -50,7 +50,7 @@ Here are some channels for you to consider to create regular communication: ### Chat Service App -You can accommodate sync communication for your community by providing a chat service app. Besides having one allowing contributors to ask questions, connect, and collaborate openly in real-time, it can also benefit you as a maintainer. You can quickly announce project updates, ask for help, hold sync office hours to talk about your projects and know your contributors better, and many more. +You can accommodate synchronous communication for your community by providing a chat service app. Besides having one allowing contributors to ask questions, connect, and collaborate openly in real-time, it can also benefit you as a maintainer. You can quickly announce project updates, ask for help, hold synchronous office hours to talk about your projects and know your contributors better, and many more. Tech communities widely use the apps mentioned here. But which one to choose is based on your preference and the needs of your community. @@ -58,7 +58,7 @@ Tech communities widely use the apps mentioned here. But which one to choose is > [Discord](https://discord.com/) is a voice, video and text communication service used by over a hundred million people to hang out and talk with their friends and communities. -The Discord market mainly targets gamers. It is a good choice if your community heavily uses group voice and video calls. Creating a channel for voice calls makes it easy for community members to join the channel and talk to anyone instantly. Discord is also suitable for building a larger community because if your server is public, anyone with a Discord account can search and join your group. +Discord is a good choice if your community heavily uses group voice and video calls. Creating a channel for voice calls makes it easy for community members to join the channel and talk to anyone instantly. Discord is also suitable for building a larger community because if your server is public, anyone with a Discord account can search and join your group. #### Slack Group @@ -90,9 +90,9 @@ Having contributors come back and continue contributing to the project is one of Start by acknowledging and thanking them for the issue or pull request they created. Ask them questions if something is not clear enough for you. Keep your message clear and short so they can understand your purpose. When you deliver a few topics, using bullet points in a comment or splitting your message into several comments is recommended. -One of the golden rules in an international remote environment is never to make an assumption. Async communication, more often than not, can lead to misunderstanding because writing is different from speaking. People with different cultural and language backgrounds might need help explaining their intentions or understanding specific cultural sayings. Consider using words with explicit meanings when you are communicating. +One of the golden rules in an international remote environment is never to make an assumption. Asynchronous communication, more often than not, can lead to misunderstanding because writing is different from speaking. People with different cultural and language backgrounds might need help explaining their intentions or understanding specific cultural sayings. Consider using words with explicit meanings when you are communicating. -Another way to engage with your contributors is by holding a regular office hour. In sync, you can hear their ideas and challenges, communicate with them about your project's direction, and more. This can be a good way to get to know your contributors closer and vice versa. +Another way to engage with your contributors is by holding regular office hours. In synchronous conversation, you can hear their ideas and challenges, communicate with them about your project's direction, and more. This can be a good way to get to know your contributors closer and vice versa. Maintainers are human. Sometimes, a discussion with a contributor can upset you when you're tired or having a bad day. Always remember that you want to foster a healthy communication and welcoming environment. So, it's okay to cool down and take time to answer them. You can take a couple of hours or even a day before you return to them to avoid a bitter tone. @@ -132,9 +132,9 @@ As your project grows and gains popularity, it will attract more contributors. C > "Hey {username}, thank you for your PR. I will take two weeks off starting tomorrow and review this upon my return. You may ask about the status of your PR if I haven't responded to it in the next three weeks." - When pull requests come during your days off, you can apologize and thank them for their patience after you return. Consider to say something like this: + When pull requests come during your days off, after you return, you can thank and let the contributors know you will review the pull requests. Consider to say something like this: - > "Hey {username}, I apologize for the late response, as I just got back from my days off. Thank you for taking on this! I need time to review it and will get back to you soon. I appreciate your patience." + > "Hey {username}, I just got back from my days off. Thank you for taking this on! I need time to review it and will get back to you soon. I appreciate your patience." - **No Private Message** @@ -162,15 +162,15 @@ Here are some techniques that you can train for active listening: - **Showing interest** - If it's a sync conversation, use eye contact to show your interest in what the speaker is saying. In an async chat, you can repeat what they are saying in your own words based on your understanding. It will show them that you are interested in their conversation. And they can correct you if you need help understanding it clearly. + If it's a synchronous conversation, use eye contact to show your interest in what the speaker is saying. In an asynchronous chat, you can repeat what they are saying in your own words based on your understanding. It will show them that you are interested in their conversation. And they can correct you if you need help understanding it clearly. - **Acknowledging emotions** - You want to be able to recognize and acknowledge the speaker's feelings in sync or async conversations. For example, you can say, "I see that it upsets you," or, "I'm excited for you!" when the speaker uses many exclamations in their writing. + You want to be able to recognize and acknowledge the speaker's feelings in synchronous or asynchronous conversations. For example, you can say, "I see that it upsets you," or, "I'm excited for you!" when the speaker uses many exclamation marks in their writing. - **Asking and clarifying** - When someone feels many emotions, they usually want to talk and let the feeling out fast. That can result in a lack of information or the inability to think of more suitable words to describe the situation. You always want to gain more information and clarify what is said. For example, "You said they contacted you on Monday [_clarifying_]. Did they file the complaint on the same day? [_asking for more information_]" + When someone feels many emotions, they usually want to talk and let their feelings out fast. That can result in a lack of information or the inability to think of more suitable words to describe the situation. You always want to gain more information and clarify what is said. For example, "You said they contacted you on Monday [_clarifying_]. Did they file the complaint on the same day? [_asking for more information_]" #### Having Empathy and Compassion From 9185e3d8d149ce1655e6fa6ccec224c42ee241e3 Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Thu, 11 Jan 2024 13:03:27 +0100 Subject: [PATCH 16/25] fix: edit Support section --- effective-communication.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/effective-communication.md b/effective-communication.md index a5f1732..cf22749 100644 --- a/effective-communication.md +++ b/effective-communication.md @@ -50,7 +50,7 @@ Here are some channels for you to consider to create regular communication: ### Chat Service App -You can accommodate synchronous communication for your community by providing a chat service app. Besides having one allowing contributors to ask questions, connect, and collaborate openly in real-time, it can also benefit you as a maintainer. You can quickly announce project updates, ask for help, hold synchronous office hours to talk about your projects and know your contributors better, and many more. +You can accommodate synchronous communication for your community by providing a chat service app. Besides having one allowing contributors to ask questions, connect, and collaborate openly in real-time, it can also benefit you as a maintainer. You can quickly announce project updates, ask for help, hold synchronous office hours, and many more. Tech communities widely use the apps mentioned here. But which one to choose is based on your preference and the needs of your community. @@ -92,8 +92,6 @@ Start by acknowledging and thanking them for the issue or pull request they crea One of the golden rules in an international remote environment is never to make an assumption. Asynchronous communication, more often than not, can lead to misunderstanding because writing is different from speaking. People with different cultural and language backgrounds might need help explaining their intentions or understanding specific cultural sayings. Consider using words with explicit meanings when you are communicating. -Another way to engage with your contributors is by holding regular office hours. In synchronous conversation, you can hear their ideas and challenges, communicate with them about your project's direction, and more. This can be a good way to get to know your contributors closer and vice versa. - Maintainers are human. Sometimes, a discussion with a contributor can upset you when you're tired or having a bad day. Always remember that you want to foster a healthy communication and welcoming environment. So, it's okay to cool down and take time to answer them. You can take a couple of hours or even a day before you return to them to avoid a bitter tone. ### Managing Expectations @@ -110,13 +108,15 @@ You might prefer contributors to add a prefix to issue, pull request titles, and #### Support -What kind of support can you provide for your contributors? Where can they reach you? You can think of these amongst other supports: +What kind of support can you provide your contributors? You can think of these amongst other supports: + +- **Space**: Where can contributors ask questions and throw ideas? +- **Pair programming**: Some contributors, especially beginners, might need extra guidance and hand-holding. Can you give them support in pair programming when necessary? How can they ask for one? +- **Office hours**: Regular office hours is a great way to engage directly with your contributors. It allows you to listen to their ideas and challenges, what needs to be improved, communicate with them about the direction of your project, and build a better relationship with them. -- Where can contributors ask questions? -- Can you give them support in pair programming when necessary? How can contributors ask for one? -- Will you hold office hours? If so, would it be regular or based on request? Where will it happen, and how will you announce it? +When you support your contributors, you can gain their trust and motivation and create a more collaborative and productive environment. By providing them with the help they need, you can establish a culture where everyone feels respected and supported, leading to even greater achievements. -You can add a section in your README or Contributing Guide to inform about the support you can give. +You can add a section in your README or Contributing Guide to inform about the support you can give and how to get one. #### Timeline From 67969c53be027e276c9a1943571872779885147d Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Thu, 11 Jan 2024 13:26:49 +0100 Subject: [PATCH 17/25] docs: add live streams --- effective-communication.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/effective-communication.md b/effective-communication.md index cf22749..2d0da7e 100644 --- a/effective-communication.md +++ b/effective-communication.md @@ -92,6 +92,8 @@ Start by acknowledging and thanking them for the issue or pull request they crea One of the golden rules in an international remote environment is never to make an assumption. Asynchronous communication, more often than not, can lead to misunderstanding because writing is different from speaking. People with different cultural and language backgrounds might need help explaining their intentions or understanding specific cultural sayings. Consider using words with explicit meanings when you are communicating. +Another way to engage with your contributors is through live streams. At OpenSauced, we do monthly live streams to thank our contributors for their pull requests and other support and give shoutouts as a token of our appreciation. You can also do live streams to work on issues publicly and ask your community to attend. + Maintainers are human. Sometimes, a discussion with a contributor can upset you when you're tired or having a bad day. Always remember that you want to foster a healthy communication and welcoming environment. So, it's okay to cool down and take time to answer them. You can take a couple of hours or even a day before you return to them to avoid a bitter tone. ### Managing Expectations From ec2cdd973cf2131988dcbef9cf220eed98c0b329 Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Thu, 11 Jan 2024 13:37:04 +0100 Subject: [PATCH 18/25] fix: paragraph format in Engaging with Contributors section --- effective-communication.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/effective-communication.md b/effective-communication.md index 2d0da7e..bf216f7 100644 --- a/effective-communication.md +++ b/effective-communication.md @@ -88,9 +88,9 @@ Effective communication is key to project success. It plays a vital role in reso Having contributors come back and continue contributing to the project is one of the maintainers' goals. To nurture this relationship, you should have time to engage with your contributors between tasks. -Start by acknowledging and thanking them for the issue or pull request they created. Ask them questions if something is not clear enough for you. Keep your message clear and short so they can understand your purpose. When you deliver a few topics, using bullet points in a comment or splitting your message into several comments is recommended. +Start by acknowledging and thanking them for the issue or pull request they created. Ask them questions if something is unclear, and don't assume. -One of the golden rules in an international remote environment is never to make an assumption. Asynchronous communication, more often than not, can lead to misunderstanding because writing is different from speaking. People with different cultural and language backgrounds might need help explaining their intentions or understanding specific cultural sayings. Consider using words with explicit meanings when you are communicating. +One of the golden rules in an international remote environment is never to make an assumption. Asynchronous communication, more often than not, can lead to misunderstanding because writing is different from speaking. People with different cultural and language backgrounds might need help explaining their intentions or understanding specific cultural sayings. Consider using words with explicit meanings when you communicate, and keep your message clear and short so they can understand your purpose. When you deliver a few topics, using bullet points in a comment or splitting your message into several comments is recommended. Another way to engage with your contributors is through live streams. At OpenSauced, we do monthly live streams to thank our contributors for their pull requests and other support and give shoutouts as a token of our appreciation. You can also do live streams to work on issues publicly and ask your community to attend. From f460d8dc4e6a2522400e255036eaf8793267a6fc Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Fri, 12 Jan 2024 21:18:05 +0100 Subject: [PATCH 19/25] fix: add sentences to point Timeline to maintainer powerups chapter * minor wording adjustment --- effective-communication.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/effective-communication.md b/effective-communication.md index bf216f7..a9239d2 100644 --- a/effective-communication.md +++ b/effective-communication.md @@ -50,7 +50,7 @@ Here are some channels for you to consider to create regular communication: ### Chat Service App -You can accommodate synchronous communication for your community by providing a chat service app. Besides having one allowing contributors to ask questions, connect, and collaborate openly in real-time, it can also benefit you as a maintainer. You can quickly announce project updates, ask for help, hold synchronous office hours, and many more. +You can accommodate synchronous communication for your community by providing a chat service app. Besides having one allowing contributors to ask questions, connect, and collaborate openly in real-time, it can also benefit you as a maintainer. You can quickly announce project updates, ask for help, hold synchronous office hours, etc. Tech communities widely use the apps mentioned here. But which one to choose is based on your preference and the needs of your community. @@ -122,7 +122,7 @@ You can add a section in your README or Contributing Guide to inform about the s #### Timeline -Let your contributors know how long they can expect you to review a pull request or to answer their questions. Inform them if you, for example, won't be available on weekends or after working hours. +Let your contributors know how long they can expect you to review a pull request or to answer their questions. Inform them if you, for example, won't be available on weekends or after working hours. You can automate this message with GitHub action if you prefer. Read our [Maintainer Power Ups](./maintainer-powerups.md) chapter for more information about GitHub actions. #### Boundaries @@ -192,7 +192,7 @@ You have a contributor who contributes multiple times and has been working fast Instead of saying: -> "Hey, why do you always deliver the code that doesn't align with what we want? I notice you've done this so many times. Do you even understand the issues? I'm also wondering if you ever run your code locally because it often doesn't work the way it should and, worst, breaks the app." +> "Hey, why do you always deliver the code that doesn't align with what we want? I notice you've done this so many times. Do you even understand the issues? I'm also curious if you ever run your code locally because it often doesn't work the way it should and, worst, breaks the app." You can say something like: From ad5f6841fe9017d2957ece751b974eb4f49d89c8 Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Fri, 12 Jan 2024 22:36:13 +0100 Subject: [PATCH 20/25] fix: improve Style Guide section --- effective-communication.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/effective-communication.md b/effective-communication.md index a9239d2..ed1a929 100644 --- a/effective-communication.md +++ b/effective-communication.md @@ -104,9 +104,11 @@ The earlier you let contributors know what they can expect from you and what you Just like maintainers, most open source contributors are volunteers. They are not required to, but they help you fix and enhance your project in their spare time. So you can't expect them to work on their issues promptly like a regular employee. With this expectation, you can, for example, break your issues into several small ones to prevent them from taking a long time to work on an issue. -#### Styling Guide +#### Style Guide -You might prefer contributors to add a prefix to issue, pull request titles, and their commit messages. Or you might select particular Markdown rules for your project. Every project has its own convention. So, don't expect your contributors to know what to do when contributing to your project. Consider communicating this in a clear styling guide they must follow. +You might prefer contributors to add a prefix in brackets to issue and pull request titles. For example, "[Bug]: Documentation link goes to 404 Page Not Found". Or you want them to follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) to their commit messages, such as `feat: add new feature for user authentication`. In another case, you might select particular Markdown rules for your project, like one underscore for italics, two asterisks for bolds, etc. + +Every project has its own convention to keep the consistency around it. So, don't expect your contributors to know what to do when contributing to your project. Consider communicating this in a clear style guide they must follow. You can take an example from GitHub's [style guide](https://docs.github.com/en/contributing/style-guide-and-content-model/style-guide). #### Support @@ -116,7 +118,7 @@ What kind of support can you provide your contributors? You can think of these a - **Pair programming**: Some contributors, especially beginners, might need extra guidance and hand-holding. Can you give them support in pair programming when necessary? How can they ask for one? - **Office hours**: Regular office hours is a great way to engage directly with your contributors. It allows you to listen to their ideas and challenges, what needs to be improved, communicate with them about the direction of your project, and build a better relationship with them. -When you support your contributors, you can gain their trust and motivation and create a more collaborative and productive environment. By providing them with the help they need, you can establish a culture where everyone feels respected and supported, leading to even greater achievements. +When you support your contributors, you can gain their trust and motivation and create a more collaborative and productive environment. By providing them with the help they need, you can establish a culture where everyone feels respected and supported, which leads to even greater achievements. You can add a section in your README or Contributing Guide to inform about the support you can give and how to get one. From 465c27bce3010094813e55579a6cf9bcf36037da Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Mon, 15 Jan 2024 20:14:46 +0100 Subject: [PATCH 21/25] fix: update Chat Service App intro paragraph --- effective-communication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/effective-communication.md b/effective-communication.md index ed1a929..664d606 100644 --- a/effective-communication.md +++ b/effective-communication.md @@ -50,7 +50,7 @@ Here are some channels for you to consider to create regular communication: ### Chat Service App -You can accommodate synchronous communication for your community by providing a chat service app. Besides having one allowing contributors to ask questions, connect, and collaborate openly in real-time, it can also benefit you as a maintainer. You can quickly announce project updates, ask for help, hold synchronous office hours, etc. +It would be best to provide a chat service app to accommodate asynchronous and synchronous communication for your community. Contributors can ask questions, connect, and collaborate openly in nearly real-time with this app, and it's also a great way to support communication in different time zones. A chat service app can also benefit you as a maintainer by quickly announcing project and community updates, asking for help, holding synchronous office hours, etc. Tech communities widely use the apps mentioned here. But which one to choose is based on your preference and the needs of your community. From fb4f89617dd2de714961326860ef95207ccbd907 Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Mon, 15 Jan 2024 20:19:33 +0100 Subject: [PATCH 22/25] fix: change contributing guidelines to all lower case --- effective-communication.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/effective-communication.md b/effective-communication.md index 664d606..c742759 100644 --- a/effective-communication.md +++ b/effective-communication.md @@ -24,7 +24,7 @@ Consider these when you write or update your documentation: - **Clear guide** - Whether it's the setup guide on the README, instructions to run and use the project, or Contributing Guidelines, you always want to provide a clear direction for contributors to follow for better collaboration. + Whether it's the setup guide on the README, instructions to run and use the project, or contributing guidelines, you always want to provide a clear direction for contributors to follow for better collaboration. - **Dedicated place for documentation** @@ -120,7 +120,7 @@ What kind of support can you provide your contributors? You can think of these a When you support your contributors, you can gain their trust and motivation and create a more collaborative and productive environment. By providing them with the help they need, you can establish a culture where everyone feels respected and supported, which leads to even greater achievements. -You can add a section in your README or Contributing Guide to inform about the support you can give and how to get one. +You can add a section in your README or contributing guidelines to inform about the support you can give and how to get one. #### Timeline From 54510368c26a5e0bf7aae3b3152599b6d309d12e Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 17 Jan 2024 14:18:50 +0100 Subject: [PATCH 23/25] fix: rename file to be more descriptive --- effective-communication.md => communication-and-collaboration.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename effective-communication.md => communication-and-collaboration.md (100%) diff --git a/effective-communication.md b/communication-and-collaboration.md similarity index 100% rename from effective-communication.md rename to communication-and-collaboration.md From 384c7b4bb88b3ca4547a885abfd1ba449e418ff9 Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 17 Jan 2024 14:21:03 +0100 Subject: [PATCH 24/25] fix: change link in sidebar.md and README to new file name --- README.md | 2 +- _layouts/sidebar.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b67e97f..307061d 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ The course is divided into X chapters, each covering a different aspect of being ### [Chapter X: Issues and Pull Requests](/issues-and-pull-requests.md) -### [Chapter X: How to Create Effective Communication and Collaboration](/effective-communication.md) +### [Chapter X: How to Create Effective Communication and Collaboration](/communication-and-collaboration.md) ### Additional Information diff --git a/_layouts/sidebar.md b/_layouts/sidebar.md index e74dbd3..299b59c 100644 --- a/_layouts/sidebar.md +++ b/_layouts/sidebar.md @@ -2,4 +2,4 @@ - [What is an Open Source Maintainer?](/intro.md) - [Setting Up Your Project](/how-to-setup-your-project.md) - [Issues and Pull Requests](/issues-and-pull-requests.md) - - [Effective Communication and Collaboration](/effective-communication.md) + - [Effective Communication and Collaboration](/communication-and-collaboration.md) From c72418ea85bf0f5b3adef21a123dc47d2a468a2e Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Fri, 19 Jan 2024 20:24:20 +0100 Subject: [PATCH 25/25] fix: change h1 --- communication-and-collaboration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/communication-and-collaboration.md b/communication-and-collaboration.md index c742759..cedd9b2 100644 --- a/communication-and-collaboration.md +++ b/communication-and-collaboration.md @@ -1,4 +1,4 @@ -# How to Effectively Communicate and Collaborate +# How to Communicate and Collaborate Effectively Effective communication and collaboration with contributors are the keys to a thriving open source community. As maintainers, you want to smoothly onboard new contributors to your projects and build a welcoming community with open lines of communication between contributors and maintainers.