theopensourceway / guidebook Goto Github PK
View Code? Open in Web Editor NEWGuidebook of open source community management best practices; is somewhat opinionated.
License: Other
Guidebook of open source community management best practices; is somewhat opinionated.
License: Other
Opensource.com explains the open source way as a set of five interlocking principles:
Is clarifying this guidebook's relationship to that definitional set of principles appropriate or desirable? And if so, then what role should those principles play in the guide's unifying narrative and/or organizational schema?
https://www.hanselman.com/blog/EasilyRenameYourGitDefaultBranchFromMasterToMain.aspx
Process:
File name in repo: communication_norms.adoc
Needs a Conclusion
Add a guidebook chapter specifically focused on communication norms in open source communities.
What are the chapters that would go into this section?
Tagging @samus-aran until she is a project member.
File name in repo: new_project_start+up+checklist.adoc
Needs a Conclusion
Not all projects need the full approach.
This chapter can distil essential advice that projects of all sizes, experiences, and history can use to establish a baseline that fits into the overall model.
First come first serve except:
Compose a guidebook chapter detailing the nature of "contribution" in an open source community. Topics may include:
Filename in repo: guiding_participants_section.adoc
Does not need a Conclusion
This isn't a high priority but just to help with establishing the teams (which I believe still need to be decided) and thus their access/permissions on the repo.
Just to get over the quick win would be setting up a team as perhaps "authors" that have either write or triage permission (and thus can assign themselves issues). I suggest at the moment triage rather than write as the editorial reviewing process hasn't been defined yet.
A few articles on the setup of the repo's access/permissions for repos.
Compose a guidebook chapter explaining what a community manager should know about organizing an open source project. Topics may include:
Going through the deliverables in the schedule, we can use:
(Updated this issue to reflect narrowed scope, as we're planning to add new template files as needs arise.—semioticrobotic)
Filename in repo: attracting_users_section.adoc
Does not need a Conclusion
Guidebook should feature a list of in-text references and suggested additional readings.
File name in repo: creating_diverse_inclusive_communities.adoc
Has a Conclusion
Compose a guidebook chapter explaining why people participate in open source communities, and what they derive from their participation. Reasons may include:
Other topics in this chapter may include:
I don't think we address this anywhere else, but it just occurred to me when looking at a diff tonight that the entire paragraph was on a single line, making a diff much, much less useful.
Aside from having a standard line length of e.g. 70 char, what are other source conventions do we need to create?
@shaunix and @bproffitt both have some experience here, yes?
Compose a guidebook chapter explaining how to increase project adoption. Topics may include:
There is a source file that I will be doing a pull request for around this, once I convert it from Google Doc:
https://docs.google.com/document/d/1LCO-gVm-_8t1cSgtpXflu6cW2Wn0qui8Y478T60MVeo
(That file is limited to Red Hat access, which is why I'm moving the contents to this repository.)
This issue is a meta tracker for any discussions around the style guide, aside from individual PRs that are changes, suggestions, and new content.
Compose a guidebook chapter outlining basic terminology necessary for understanding the guide.
Compose a guidebook chapter surveying some common mistakes community managers tend to make (and explaining how to avoid them, if possible!). Topics may include:
We should update the README.md file. Things we might include, feel free to add:
Compose a guidebook chapter explaining open source software project basics.
File name in repo: measuring_success_section.adoc
Does not need a Conclusion
This column can be skipped if not applicable for a given chapter, but we should have it just in case it is needed for a chapter.
File name in repo: developing_a_metrics_plan.adoc
Needs a Conclusion
Compose a guidebook chapter explaining various metrics community managers can use to assess the health, well-being, and growth of their communities.
It would be great to have instructions on how to build and serve the content for the site - perhaps a Dockerfile. If I have that, I would be happy to put together a devfile.yaml file so that people can try & edit the content directly in che.openshift.io.
In advance of our planned SCaLE 18x workshop, we might consider developing a short (roughly 10-minute) "project overview" pitch for in-person delivery to project newcomers.
The pitch should cover:
File name in repo: community_manager_self_care.adoc
Needs a Conclusion
Compose a guidebook chapter explaining the importance of community manager self-care, with tactics and resources for maintaining healthy community management behaviors.
In #69, contributor @samus-aran proposed an excellent overview of this material. Let's consider beginning this work as a chapter and broadening to an entire section of chapters if a single chapter grows large enough to warrant.
Here is what we need to do as part of publishing a schedule:
File name in repo: community_governance.adoc
Needs a Conclusion
Compose a guidebook chapter surveying basic legal and governance issues open source community managers may face. Topics may include:
As we articulate the scope and purpose of this guidebook (particularly in conjunction with #3), we might consider surveying the landscape of currently existing guides in order to determine the form(s) of value we intend to offer through our work and the audience(s) we intend to reach with it.
Questions to consider might include:
I'll use this thread to begin sketching the landscape and identifying key sources of inspiration. Hoping others will do the same!
Compose a guidebook chapter explaining the many ways community participants contribute to open source projects. Examples may include:
Other topics may include:
File in repo: onboarding.adoc
Needs a Conclusion.
Compose a guidebook chapter explaining basic components of effective community onboarding processes. Topics may include:
Fine name in repo: growing_contribuots_section.adoc
Does not need a Conclusion
Can cover the arc from user to contributor, especially for people who jump right to this chapter, trying to skip fundamentals. This introduction should point back to the fundamentals.
File name in repo: getting_started_section.adoc
Does not need a Conclusion
I've edited this in the chapters I worked on, but we need to be careful to update a lot of terminology from the words that may have been used in OSW#1. I'd like to use this issue to keep a running tally of them.
The ones I've run across include:
Add the other out-of-date terms you've run across so that we don't accidentally keep them in the draft. Thanks!
This should set the tone and stage for the whole book.
Start with a visionary introduction to work against.
File name in repo: communtiy_roles.adoc
Needs a Conclusion
Compose a guidebook chapter explaining various roles contributors can play in an open source project community. Topics may include:
We have a landing page, opensource.com/open-source-way, that has well over 20,000 readers over the last couple of years. It'd make sense to add a short section with what this project does and how it relates to the definition.
The prep brief is the abstract: https://fosdem.org/2020/schedule/event/bof_open_source_way/
We will begin the BOF with a brief introduction to the guide itself, what is covered within it currently, and an overview of the narrative being told from/to community management practitioners. We'll then get hands-on with the contribution process, starting with a walk through for what is needed for the 2.0 release. After we do some real-time submissions to the guide, the BOF participants can begin working together in small groups or individually on portions of the guide, including both content and publication toolchain.
Tasks/deliverables needed to be in place/ready by 31 January 2020:
We need:
Write a guidebook chapter on best practices for converting project users into project contributors.
While this has been on the outline for some time, I cannot find the appropriate issue linked to it (hence creating this one).
I would like to nominate @dneary as author here, because a great deal of his material already forms the crucible of this chapter (especially if we merge #94).
Compose a guidebook chapter explaining concepts fundamental to open source community management. Topics may include:
File name in repo: creating_diverse_inclusive_communities.adoc
Needs a Conclusion
Discuss the range of initiatives aimed at bringing more women and minorities into tech.
Pivot to discussing the disconnect between these opportunities and low rates of minority participation in tech, especially open source
Start by emphasizing that open source - which should theoretically be the most "meritocratic" tech ecosystem - is less diverse than tech at large, citing stats from Stack Overflow's latest survey.
Pivot to dismantling the "pipeline problem" myth that there aren't "enough" minorities with the skills required, explaining that the rates of minority CS graduates are higher than respective rates of CS employees.
Using a case study, explain that when minorities do enter tech spaces, they often feel alien and marginalized. This causes them to leave, perpetuating the problem.
Main point: If you haven't built an inclusive community, your diversity initiatives will fail.
Diversity and Inclusion Aren't Synonyms
They address different aspects of the same problem: Exclusionary Success
Too often, diversity is a due diligence box for businesses to check
But no one joins open source projects to check a box - they do it because, to quote W.E.B. DuBois, "We want to be creators in the kingdom of culture."
Share some stats on how inclusive OS communities - those that put inclusion at their strategies' core - are more successful. Quantify "success" here in terms of PRs, number of releases, number of maintainers/contributors, etc.
Reinforce this with stats from Deloitte where 80% of employees say inclusion matters when selecting employers, and 72% would leave one employer for a more inclusive one.
Conclusion: If your OS community isn't inclusive, you won't grow your contributor base and your project will lose relevance.
Acknowledge your own bias
Audit your communities based on diversity (gender, POC, neurodivergence, etc.)
Seek out sources for new, diverse OS contributors, like CHAOSS/the Linux Foundation and Project Include
Give your community open and private options to leave feedback on their experiences. This can range from quarterly surveys to giving contributors the freedom to create channels in the project's Slack, Discourse, etc. chat about mental health, being a person of color, how to handle negotiations, etc.
Create and reward skills-based teams.
Assign new contributors to senior maintainers
Use influence to promote proteges
Assign proteges to PRs that match their interests/expertise. This saves them hours of searching for open PRs on new, unfamiliar projects
Take the steps above BEFORE trying to recruit diverse OS project contributors, because inclusive change starts from within.
So I initially wanted to reply to #91 where @jberkus mentioned that mailing lists (and IRC!) are no longer the most common communication tool, but this is perhaps a bit bigger thing that is worth its own issue. This is a sort of a late night brain dump that branches into two directions: new community roles, and new communication tools for community presence, and I wanted to get some ideas out so we can discuss them. Also apologies if some of these are already part of the TOSW2.0 content, I will need to review the existing chapters.
I have noticed that on non-software-development related open source projects there is often a separate user community that is not necessarily connected to the development of the project.
They are a fairly common way to run a user community on open source projects where the user base consists of mostly non-developers who are not familiar with tools like Slack. Due to the different tools used, these communities also might or might not be connected to the actual developers of the project, who often are using Slack and GitHub issues and pull requests for actual development.
The FB group also has a number of people who are helping newcomers get started, which is an important role in a project, and easily makes those who get help more likely to help other newcomers in return.
It seems fairly common that a lot of documentation (especially "getting started" and tutorial type things) exist in YouTube these days, and people go there to learn to use things. Some authors related to the more popular open source / DIY projects can even support their video creation with the YouTube ad revenue.
I just committed a very basic .adoc file with includes to have a simple way to test the build locally. This is a scratch file that can stick around the repo as long as it is useful: 5162d3d
Idea here is to have an easy way to test out some organizations in building without having to mess with a formal book file.
File name in repo: defining_healthy_communities.adoc
Needs a Conclusion
Compose a guidebook chapter offering advice on building and nurturing healthy communities. Topics may include:
Compose a guidebook chapter on the finer points of code migration. Topics may include:
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.