defining_healthy_communities.adoc

Defining Healthy Communities

Introduction

While we know that no one wants to live and work in an unhealthy community, we also know that it’s complex to define and maintain health. First you have to know what you consider to be a healthy situation and set of behaviors. Then you have to check (test) those situations and behaviors over time so you can dynamically predict and respond to maintain health.

What is healthy may change it’s definition over time, as your community evolves. Early on you are going to be putting a lot of effort into having a healthy community for users, especially around how you take in and manage feedback. As you evolve into or grow as a contributor project, the definitions of healthy and how to maintain become exponentially complex.

However, once you have decided that having a contributor-based open source software community is your goal, you can be aware of and focus on the entirety from the beginning. A project that understands and is healthy at the contributor level, is naturally going to express that health into the other layers of participation and for end users. That is, healthy contributors are involved in creating safe and healthy environments for others as a direct focus and/or side effect of the work they do in being healthy.

As an example, let’s presume that kindness is a behavior you consider to be healthy for contributors to have between each other. Kindness toward immediate peers is one way to conduct this behavior. But in open source we can see that extending kindness to each person who enters the project’s sphere not only gives them a good experience, it means they extend that kindness into how they interact in the rest project. If your kindess can turn ten users into being more kind toward your fellow contributors, you have magnified that kindness beyond what you can give that peer directly.

Defining healthy communities

There are two main ways we consider when viewing the health of an open source community.

Because attracting users is a key to success, we look at how the world sees the project. These are the signs people look for when they see a project, from activity levels to maintainer interactions.

Because attracting and maintaining participants and contributors is a key of existence, we look at how a project considers its own health.

How the world sees the project

Later in this chapter we look at how to conduct an audit that measures the health of this aspect of a project. In that audit, you’ll see the main top-line questions from here as categories for more in-depth questions. Those questions in the audit section go into further details of the category.

Structure

This is the structure of things people see and perceive as they visit your project. If it were a building, it would be the number of floors, can you walk in the front door, is it accessible to wheelchairs and baby-strollers, is there a clear sign with the street address, is there a directory in the lobby so you know where to go, is the lobby well-lit and safe looking, and so forth.

• Does the project have a website with a unique/memorable name?

• Does the website have the elements needed for an open source project?

• Does the website make clear the project’s purpose, how to get and use its software, and so forth?

• Does the project have a Code of Conduct?

• Does the project have a diversity and inclusion effort?

• Does the project put its diversity and inclusion efforts up front?

Release Management

What is the project’s discipline and process around releasing software for end users?

• Does the project release software?

• Has it done a release?

• What other types of artifacts are released?

• What type of development cycle/model are they striving for?

Activity

How active is the development of code and content for the project? This requires looking at the project’s code and content repositories.

• What are the release activity data?

• What is the commits activity?

• What is the bug reports activity?

• What is the events and meeting activity?

• What is the mailing lists activity?

• What are the communication channels the project uses, in what priority?

Documentation

This is content useful to a range of people, including end users, developers using or integrating the software, and contributors to the project.

• What is the overall quality of the documentation?

• How is documentation created?

• Who creates the documentation?

Code Quality

This is a health area that has been evolving. From when this guidebook first looked at code quality in the 1.0 version to now, there has been a large growth of languages, development enviroments, and schools of thought about how to solve common problems. This category is the most subjective in this chapter.

• What is the overall quality of the code?

Outreach

From attracting users, through exciting participation, to connecting people for collaboration, the way a project reaches out to the world is an important aspect of project health.

• What are the downloads data?

• What are the blogs data?

• What are the social media data?

• What are the events data?

• What are the communication data?

License

This is a binary situation: does the project have an Open Source Initiative approved license, or not?

• What kind of license does the project have?

How the project sees and understands itself

This is a highly subject mix, and as a project ourselves, the authors of this guidebook are still exploring this material. For this chapter, we offer a list of considerations that seem generally applicable.

• How is diversity from all angles

• How is organizational diversity alongside other, more important groups?

  • This is a non-special awareness particular to open source software: projects dominated by a single organization/company are limiting their potential in not being organizationally diverse. That is, the value that diversity brings also applies to having people from diverse organizations.

• What is the sense of psychological safety? Overall and within teams?

• Is it clear how to progress in the project toward more responsibility, leadership, and influence? (This is all the governance/merit stuff as it actually works day-to-day.)

• How hard is it to DO something?

• What is the level of automation? Is this level from technical debt, job security, something else?

• What is the level of cookie licking going on? (This is when known contributors, by speaking up or being present, are presumed by others to own the problem/situation/whatever.)

• How are things going with cliques? Cliques are a natural social mechanism, which arise in open source communities, and can be a source of joy and fun and productivity, as well as sorrow and angst and feeling left out.

• Rules aren’t always followed; what is the percentage and feeling of the project following its own guidelines? What are the types of rules less followed and more followed?

• Is there a sense across the project of a healthy work/life balance?

• Is there a culture of mentorship?

• How is the process and pain and results around self-documentation?

• Do the kids have shoes? Does the roof leak?

• What are the broken stairs? A broken stair is a term for something dysfunctional in a community, which everyone learns to just work around rather than talk about it and get it fixed.

• How is the sympatico, the interpersonal relationship quality between individuals?

Building healthy communities

The actual process and experience of building out an open source community is particular to each situation. That is, it’s not unique in it’s parts, but it is unique in it’s composition. This means you can take various truisms (best practices) and apply them to your particular situation, even though your situation will never resemble a step-by-step process.

Following are elements that allow the building and growth of healthy communites.

Communities require care, feeding, and weeding to get started

Imagine if you grow a garden and are very ambitious. The first year you overplant and are unwilling to thin out the seedlings. You end up with overcrowded, unhealthy plants.

In online communities (including open source communities), there is a strong drive for immediate and explosive growth. This is usually achieved by promoting the project in as many environments as are appropriate, with the result that many people join the community out of casual interest. There’s often a strong impulse to accept early adopters as committers, to create the impression of a viable, strong team.

Contributing community members—those who affect the actual direction of the project—should be chosen based on how much they actually contribute, and the value of their contributions, and overall consensus. If someone contributes fixes to a number of critical bugs, perhaps they should get write access for the project (and a corresponding voice); if, however, that same person creates a poisonous atmosphere for the community, then promotion to maintainer is not a good idea.

It’s also worthwhile to take note of core community members, rewarding those who contribute regardless of coding ability. For example, consider someone who is great at helping new users but hasn’t tried to fix bugs—recognizing those contributions creates a positive impression for that user and everyone else. Positive motivation encourages others to do what garnered the reward, which in turn makes the entire community more strong.

Growth should always be encouraged, by the entire community; just try to assure that the growth is composed of candidates who’ve earned membership. This does not mean that everyone has to get along perfectly at all times; personality conflicts are certainly possible (and likely, in some cases). However, the community at large shouldn’t allow specific members' opinions to make primary decisions like this; seek consensus rather than responding to the urging of a small subset.

Of course, a member’s actions might be severe enough to warrant a response. Use reason; consider whether anyone would be caught by surprise if an action is taken.

Embrace failure

Fail spectacularly, and don’t forget to take notes.

There is a lot of crowd wisdom at work here. It’s basic physics, too — if you charge ahead and fall on your face, you at least made headway. Like feeling your way around in the dark, each touch, bump, and stub of the toe teaches you more about the environment.

When you drive your processes and technology to the brink of failure, repeatedly, you get very comfortable somewhere most people don’t even want to go. You also get to set a new standard for what is comfortable for your community, giving you new room to expand even further.

Culture of transparency

One of the most important elements of an open source community is the level and quality of transparency. Humans need private space, for certain, and that supports our ability to conduct ourselves in public space. Ultimately, all discussions and decisions need to held in front of the entire community. This builds trust, handles objections by including feedback as solutions along the way, and builds toward a community acting as a chorus. Key parts of this element include:

Take extra extra extra care to have all discussions in the open

Even if it means stopping and restarting a conversation in a public/archived location, keep this in mind at all times.

If it’s not in the public record, then it doesn’t exist.

This means that when you have private discussions, and such hallway conversations do happen, the responsibility is on the participants to record as best as possible the conversation — notes taken in the middle and at the end can suffice as such documentation. The results of this discussion, minus privately sensitive matters, must be sent to the main openly archived discussion area, such as the community mailing list.

Remember that such discussions are not where decisions are made. You can decide on a recommendation, but that must be made to the larger body and openly decided with all able to participate.

Trust but verify. A commitment to participatory transparency invests into the mutually held bank of trust. "Just trust us" decisions done behind closed doors spend from the bank of trust. The bank can go broke all too easily.

Radically visible meetings at all times

Any private interactions, from the hallway to email/irc to phone calls, are a risk to the project. At the minimum, you must be mindful of reporting back the results of direct conversation.

However, this isn’t really good enough. A summary of a meeting never shows the reasoned discussion, effectively cutting the community out of the decision making process.

There is a reason forums, mailing lists, open chat networks, and repo comments and logs are the baseline for all communication in successful open source projects.

No decision point is too small to pre-announce to a mailing list

While we can grow trust in the community about technical or other decisions, there are common problem circumstances we can avoid.

The corporate sponsor and staff are always more suspect, so need to take extra care to share the decision making process.

We cannot guess what is important to contributors, nor why. Presuming they don’t care about a decision is a bad idea.

The method is to take all decisions to the open forums, until people start complaining that a particular class of decisions can happen in another way/place. This is called, "Building trust by proof through annoying transparency."

It’s okay to be disappointed but never okay to be surprised

No one is going to like every decision made, and people will be disappointed. That is a fact of life we cannot avoid.

However, no one should ever be surprised, especially by something perceived as negative. It is a morale killer and eventually drives people away.

Sometimes we hold back on letting people know information because we are concerned they’ll be disappointed. When mishandled, those folks end up disappointed and surprised, which is a potently negative combination.

You may need to inform people in a private communication channel, and should do so often where there is a chance they may not know or could not know a decision.

If you find people being surprised too often, do a serious review of your communication methods. For some reason, you are not reaching enough of the people for word to spread.

Don’t bury decisions in other text that people don’t read. As with a software patch, people can understand changes better when they arrive in discrete chunks to the community commons, such as a mailing list or blog planet. You may need to split decisions or discussion points out to individual threads so people can see the various trees as well as the forest.

If you find a decision or detail is buried in a discussion and people might miss it, find a way to highlight it so that people are not surprised later.

Take even more care to do all design decisions in the open

Even when all content is done using open resources, if you make design decisions via in-person meetings, hallway discussions, over lunch, during the daily commute, and so forth, then you are leaving the community out of work that really matters. They’ll notice and care.

People talk with each other, and that’s fine. Just consider it to be pre-decision discussions and follow these rules:

• A decision doesn’t exist unless it’s discussed in the common forums first.

• A conclusion isn’t justified unless the discussion demonstrating it and evidence backing it up are visible publicly.

• A discussion doesn’t exist unless it’s on the community forum—send at least a summary of all non-public discussions to the mailing list, with the conclusions open for further discussion.

Do not put any non-public blocking steps in your process

You must not have anything that can block a release or development process be non-public. For example, you don’t want to be in the position of telling your community something is broken in a private test environment and you can’t recreate if for their review.

Look through your entire process, identify the non-public parts, and figure out how to expose them.

You may have some testing and development infrastructure that is non-public and need to work out how to make them public. In some cases, the best you can do (for at least the short-term) is to make reports public. You may end up helping other people to create a similar environment in a public cloud simply to make sure processes are kept flowing.

Use version control for your content as well as code

That way everyone can watch the changes.

Being able to roll back work encourages people to be bold and innovative. One of the currencies of project work is simply making a change to a codebase or a document as an explanation itself. Changes are self-evident in the commit itself. This is why all changes must be accompanied with a comment or summary that explains the reasons behind the change.

Version control for your documentation is the meta-documentation that provides the context of why.

Equally important is that all project members watch these changes. Responding to the changes on a forum, bug report, or documentation discussion page keeps the discussion associated with the node of origin.

Choose open tools that can be extended

Don’t choose tools just because your small team knows them the best. Be careful of choosing something because you are in a hurry and need something quickly.

When it comes to tools, talk with trusted community leaders about what you should use. Make governance as clear as possible Even if you choose something out of step with other community members, you will at least know why you did and be prepared to mitigate risk.

It is risky to choose closed tools that a community cannot easily scale itself.

Make sure everyone has an equal and clear method for access to write-commit to open tools

With version control under code and content, you can open access to more people. For example, don’t require people to go through a lengthy process or to "prove" themselves with X number of patches. Give people access to whatever they need to make a difference, even if they don’t use the access.

Wikipedia is a prime example here. They use the power of the community size to police bad content changes, rather than limiting the community size behind rules of what it takes to write content changes.

More people want to do good for your project than want to do bad. Don’t punish the do-gooders because of the potential evil someone might do.

Make governance as clear as possible

Whatever they are looking for, whatever they need, your contributor community does not want a confusing governance structure.

Listen to feedback and make document changes to evolve the language and understanding

From that may come evolution of the governance itself, with the corresponding transparency at getting there.

Do not let poisonous people bog down the community

Remember the paradox of tolerance: if you are tolerant without limit, your ability to be tolerant is eventually seized or destroyed by the intolerant.

Seek consensus, use voting as a last resort

Most decisions in an open community are not decided by a vote. As in a well-working democracy, decisions are handled by the experts and knowledgeable people who are in charge at the will of the people around them.

Voting is best left for deciding who is in charge and the occasional very contentious issue. Don’t you wish it weren’t contentious? Wish you could go back and make a consensus?

Do not forget to release early and release often

It’s crucial to the success of an open collaboration that no part of the work is held back "until it’s just right."

Many of us have the tendency to keep code, content, or ideas to ourselves until we get them finished enough, polished enough for others to review. In open source development methodologies, that perfection seeking is the enemy of the good enough.

Innovation is a process of building on existing ideas, in novel or even repetitive ways. We need others to see our ideas early and often so their influence can improve the ideas before they are too fixed to be improved.

Make it the rule that nothing is held back until finished. Treat it like a Zen practice—release early and often, every day or every hour if need-be.

Release early and release often is for more than just code

Every idea deserves the light of day as early as possible.

A common mistake is to wait to release a document, process, marketing plan, etc. until it is "just right". People who otherwise fully understand how not to do this in code forget when it comes to other parts of a project.

Apply this rule:

• If a piece of information is confidential, keep it private;

• Otherwise, get it out in the public soonest using techniques such as:

  • Bounce the idea off the mailing list(s)/forums

  • Make a wiki page

  • Add to another wiki page

  • File a ticket in a tracking system

  • Make a non-coding prototype

    • Wireform web page in a wysiwyg editor

    • Graphical mock-up/collage

    • Bar napkin and pen, scanned or photographed

Evolve with the growth of your audience and contributors

It’s easy to say, "We designed this for such-and-such a reason for this particular audience." It’s not so easy to be the only creator and maintainer, though. If you want to grow beyond just you and your niche group, you have to be willing to accept the influx of new ideas and directions that comes with open collaboration.

Use a predictable schedule type and stick to it

There is a lot of disagreement over how fast an open source project should move. Many projects have found the six month release cycle is not too long nor too short.

Regardless of what type of schedule you choose, you need to stick to it and keep your community informed about the status of the schedule. Remember, it’s OK to disappoint people sometimes, but not surprise them.

There are two main types of schedule for delivering open source:

• Time based

• Feature based

One reason time based schedules are used so often in open source is that it forces developers to release early and often, and not sit on code waiting for a feature to be completed. Incremental updates provide the community a chance to keep up, help, and contribute.

Even if you follow a feature based schedule, it is useful to break it down to smaller, time-based deliverables. This keeps your community interested and able to test, knowing that at regular, predictable intervals there will be something for them to try out.

A good teacher is a good student - ask questions and put yourself in a position of being taught by others

People of all ages and experience levels have knowledge and curiosity to contribute. You can engage with what they know and what they want to know by putting yourself in the position of learning from them, even as they may be learning from you.

Part of practicing the open source way is teaching others about how and why they want to adopt this way of working, thinking, and acting.

In all your interactions, it helps for you not to presume that you are an expert and know all there is to know. Even in domains you are familiar with, ask basic and dumb and open and revealing questions. Ask any questions that help you make sure to reveal and map the principles of The Open Source Way to an individual domain.

Strive to drive barriers as low as possible

Open projects need to have low barriers of entry. People and organizations are giving of their time and other resources, so if you are going to make them leap over any barrier, it needs to be a clear barrier with a clear reason. Otherwise, it’s an invisible problem that makes people disappear before you even know they are there.

If new participants come along and run in to a real, implied, or accidental barrier, a certain percentage of them will just walk away at that moment. At the very least, if you inform those people of what the barriers are and why they are there, then these folks will walk away informed instead of bailing out of ignorance.

If you want open collaborators, you must make all barriers as low as possible. You must advertise this access-level clearly.

If there are levels of access, such as "can write to the mailing list and file bugs" all the way over to "can commit major code changes to the source repository", then you must make it clear what these levels are and how to obtain them.

Wikipedia is an example of everyone entering at the same level. There are, however, community levels that are implied and centered around a group of information pages. It is easy to make an edit on a page, even anonymously, but to get that edit to stick (not be reverted by another page watcher in the information community), other, more invisible barriers need to be overcome. This may discourage some casual editors, if the information community around a set of pages are very strict about allowing anonymous edits. Other pages may not have that strict of an information community around them, so anonymous edits are stickier. In the end, this may affect Wikipedia’s reputation—some people have experienced or perceive that Wikipedia has an invisible barrier to entry they can’t see or overcome.

Highlight activity and participation

People want to see themselves and to see what others are up to. It is why sitting at a cafe is considered more special than having coffee at home. It is a social space, just as the elements of an open source community happen in social space.

Build systems and processes that make it easy to highlight the activity within the community. In some cases, this might be gamification, with badges, leaderboards, and the like.

In most cases, this includes making sure that everyone is acknowledged by name and type/area of contribution when you conduct a release.

Turn newcomers into instant contributors with the Power of To-Document

Make your community culture be to document answers when asking for help. Ideally, the documenting should be done by the asker. And systems should make it easy for them to do so.

People offering help can require that the help be documented.

When the asker is a new member of the community, this is a great way to turn them into an instant contributor.

Four shared virtues

These four virtues were described by Brian Fitzpatrick and Ben Collins-Sussman in their seminal talk on avoiding poisonous people in communities.

• Politeness

• Respect

• Trust

• Humility

These virtues need to be implemented in every part of the community. Public and private discussions, all communication channels from in person to IRC, and sometimes even in the nature of the project itself.

Have a clear understanding of the users (and contributors) you hope to assist and engage

This is something that comes from your initial project and community planning. It should form some part of your metrics plan, the way you measure the ongoing health of your community for what it provides to its members.

When there is evolution in thinking here, as the project changes, this clear understanding needs to be updated. There is a side-effect of feature creep—the phenomenon of how the quantity of features increase via input from users and stakeholders while development is underway. Features that creep and sneak their way into a release may end up attracting more and different users and contributors.

These new people are not a bad thing in any way. But if they are unexpected and unnoticed, they become an underserved part of the community. In their bubble, this underserved group has its own understanding of what the project and software needs to do for them. Until you open that bubble and include them in the community view as a whole, their entire worldview is at risk whenever a change comes through the project.

Healthy projects entail thoroughly documented (and continuously evolving) governance models.

Governance is not a static document and process to be adhered to year after year.

As the project evolves along many lines, so should the governance evolve in response, and even in anticipation.

You should have robust change management for governance and encourage it to be used early and often.

Governance is covered further in the chapter "Project and Community Governance".

Visible leadership

Whoever is in charge of the largest or smallest things, it needs to be clear who they are, how to reach them, and so forth.

Leaders should be out in front, doing the work with others.

This is all part of the idea of what some call a _do-ocracy—a culture of those who do things become responsible for getting things done.

Clear responsibilities for leaders

In healthy projects, members have formally documented release processes and identified release managers to supervise those processes.

Healthy open source projects have publicly shared goals and clear processes for reaching those goals. Goals are attainable and clear deadlines exist for tracking progress toward those goals.

Community audits

The audit process outlined in this chapter uses a worksheet when conducting the audit. In this case, we have the first worksheet available for the external health check.

You can download the file here:

https://github.com/theopensourceway/guidebook/blob/master/worksheet_for_community_audits.ods

This is an Open Document Format spreadsheet with the following features:

• First sheet "Overview" is a single overview of all the questions.

• These questions are in the form of a main question that forms the basis for the sub-questions. The sub-questions may not be applicable to each project, but the main questions always are.

• Each section such as "Structure", "Release Management", and "Outreach" has it’s sheet with the sub-questions.

• Scoring or notes can be kept on each sheet for roll-up purposes.

• There is a concept of a health percentage by how many of the questions in each section are answered "yes" or in the positive. A "no" or negative response indicates something essential may be missing or in trouble in the project.

This list is not comprehensive per-se, but we feel it represents a good overview of what a single, determined individual can discover about a project with one to four hour’s of attention and interest. That is, if a user comes to your website and has a positive experience that leads them to becoming a contributor, it is greatly influenced by the set of elements this audit looks at. These are the control points you have for helping that experience turn out positive.

Here is the overview of a process for using this worksheet:

1. Give yourself up to 30 minutes per section (labeled sheets); any more time than that may indicate this is an area with a problem or something that doesn’t fit with the audit process. Make a note and move on.

2. Work only with publicly available information; don’t seek out project maintainers for answers, the point of the audit is to see what the average person experiences.

3. You can parse out the sheets to other people who have more expertise in that area, if it helps.

4. A health "score" can be derived by tallying up all the parts that are in place or good enough as is, compared to how many are missing or needing improvement.

5. When you are done, write up a report with a narrative that explains the missing or needing improvement parts.

   • Be aware that at times you may not be aware of a practice that is sufficient but not apparent, because of some aspect of the programming language, build systems, etc.

Addressing mental health and burnout of moderators and community leads

The sub-section is here to remind you to seriously consider the mental health and burnout risks for members of your community.

Community leaders hold an important role of holding the project together, especially when things are not going well in the world and lives of the other contributors. For this reason, we have a complete discussion for people who are in this role in the chapter on self-care strategies for community managers.

Individual community members are subject to many of the same stresses, responses, and situations as community leaders. You will find that chapter largely applicable to any community member, although it addresses and focuses primarily on community managers.

In addition to those materials, there are some other areas to consider that apply to all members of the community:

Burnout

Anyone in the project can experience burnout. In addition to the effects of the individual’s choices that may lead to burnout, there are a number of systemic and institutional causes of burnout. You may not be able to fix all of them, but acknowledging they exist can go a long way toward helping people feel less personally responsible for things that are out of their hands to effect.

Self-care to community-care

Self care is often focused on the responsibility of the individual. Of course, as individuals we have a personal responsibility for our well-being but we often are responding to the culture, policies, and procedures of the systems we’re working with/engaging with. A community-care approach focuses on lightening the burden of the individual by bringing in the structure and support of the community as a whole.

Social strategies

As part of community-care, this may provide strategies for managing self-care. Engaging people with appreciation, joy, and acceptance is an antidote to feelings of not being enough, low motivation, and feeling apart—even all the way to feelings of guilt and shame.