theopensourceway / guidebook Goto Github PK

Opensource.com explains the open source way as a set of five interlocking principles:

• Transparency
• Collaboration
• Release early and often
• Meritocracy
• Community

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:

1. Bring up on mailing list to bring awareness to coming change
2. Confirm what people need to do in order to change their copies of the repo
3. Plan and do the change

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:

• SMEs?
• not enough experience?
• more than one taker at a time?
• can't collaborate effectively to co-author?

Compose a guidebook chapter detailing the nature of "contribution" in an open source community. Topics may include:

• How a contribution is different than other actions
• What it constitutes, aka types of contribution
• Directly feed into project—software roles, etc.

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.

• create teams on theopensourceway with appropriate permissions
  -- Setting permissions allows new members to correctly assign themselves to issues to thus take ownership
  -- allows members to mention teams instead of individual members to lighten individuals' workload
• establish distinction of team member or collaborators (not really a difference but some may prefer not to be associated with another organisation in order to contribute/take ownership of tasks).

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.

https://help.github.com/en/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization

https://help.github.com/en/github/setting-up-and-managing-organizations-and-teams/setting-base-permissions-for-an-organization#setting-base-permissions

Compose a guidebook chapter explaining what a community manager should know about organizing an open source project. Topics may include:

• "Good enough to get started"
• Generating a vision and mission
• Setting project goals
• Balancing competing priorities
• What you will need—defining your project roadmap
• Lowering barriers to user participation and contribution
• Outreach to find new contributors—being active from the start
• Best practices for organizing a distributed projects/communities

Going through the deliverables in the schedule, we can use:

• Template for a chapter outline
• Template for a chapter
• Template for a "why" story: interview (video, email); self-written
• Template for a chapter lexicon
• Template for an interview transcript

(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:

• To use more of your cool software
• To tell other people about the software maybe recommend they use it
• To wear swag of projects they love
• To participate in online forums to get help and help others
• To attend events and meet some of the people who work on the project

Other topics in this chapter may include:

• Rewarding contributors (For profit-generating projects, how to you reward contributors when
  there's money flowing, especially outside employment? Does paying
  contributors dis-incentivize people from contributing without pay?)

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:

• Making a plan
• Acquiring funding and resources (corporate sponsors, foundations, programs, and more)
• Running conferences and hackfests

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:

• Handling loss of contributors, off-boarding, and succession
• How to decide when to end a project
• Best practices for ending a project gracefully
• Forking or taking over projects (esp. with regard to trademarks)

We should update the README.md file. Things we might include, feel free to add:

• What the repo is
• Who's responsible for stuff
• How to contribute
• Where the mailing list is

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:

• What the project is
• Why the project exists
• How the project is funded and supported
• How participants can get involved

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:

• Update readme
• Assign milestones to issues
• Communicate widely what the schedule is, get started
• Make sure communication channels are open and explained

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:

• Free software
• Open source software
• Why standards matter
• Why governance
• Who can participate
• Governance models
• Foundations
• Trademarks
• Who makes the decisions
• Resolving conflicts between stakeholders (Aside from personal conflicts, there can be legitimate differences in technical direction that can affect how your project progresses.)

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:

• What will this guide offer that others currently do not?
• What specific forms of value and knowledge do we hope to provide readers and collaborators?
• What do we hope someone who engages with our work be able to do (or do better) once they've interacted with it?
• What will compel contributors to invest in this work rather than in others?

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:

• Share their personal story around your software with their friends family co-workers complete strangers, etc.
• Generate energy at events talks, etc.
• Cross connect people and events with you and your software
• Help amplify your message

Other topics may include:

• Methods for encouraging (and discouraging) certain types of contributions

File in repo: onboarding.adoc

Needs a Conclusion.

Compose a guidebook chapter explaining basic components of effective community onboarding processes. Topics may include:

• Principles of onboarding
• Building onboarding platforms
• Attracting contributors

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:

• Fork a Project: because of git and Github, the term "fork" now refers to a code management operation and not a social action. Use "split a project" or "project splitting" instead.
• BDFL: due to numerous high-profile conflicts between the most prominent BDFLs and members of their communities, the "B" in "BDFL" is taken by a lot of readers to be ironic. In most cases, use "project founder" instead.
• Meritocracy: likewise, the term "meritocracy" has become a charged word because of publicized abuses of the term, and should not be used casually. Use "do-ocracy", "contributor-led", or similar terms instead.
• Mailing List: there's an assumption that an email list will be most project's communication format of record. Many projects today use some form of chat, or Github or Gitlab issues, Kanban boards, or even GoogleDocs as their primary communication mechanism. So use "mailing list" to refer to actual email lists, but when you want to say "project communication" say that.

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:

• Development
• Debugging and testing
• Documentation
• Graphic design
• Advocacy and marketing
• Resource management

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:

• Slide deck that includes intro slide, guide TOC, narrative overview w/ pictures, something that shows who is responsible for what, something that shows the content creation process as a chart
• An up-to-date list of what is needed for 2.0 release
• A working contribution process that can be shown, tested, and used in the BOF
• Test real-time submission process from BOF room
• Small group tasks -- planning, reviewing, editing, toolchain hacking, writing assignments

We need:

• One or more persons identified from specific professions/expertise to review the corresponding chapter content.
• May need a specific approach per topic, as different professional ethics and standards (may) apply.
• Appropriate language in the content that indicates the review, to whatever extent that makes sense.

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:

• You've decided you want a community project
• Real-world benefits of community
• Drawbacks of community
• Who are the community?
• Community health
• Defining community manager
• Balancing the needs/dynamics of upstream and downstream
• Maximizing value

File name in repo: creating_diverse_inclusive_communities.adoc

Needs a Conclusion

Intro

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

The State of Open Source Diversity in Tech

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.

The Diversity Paradox

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.

Tips to Attract and Retain Inclusive OS Communities

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

Conclusion

Take the steps above BEFORE trying to recruit diverse OS project contributors, because inclusive change starts from within.

Include more information in the README as guidance for first-time contributors with details on how to get started and where to go for more information for this specific project.

Added during the Open Source Way workshop at SCaLE18x

CC @quaid

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.

Facebook groups

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.

• INAV Fixed Wing Group is a user group
  related to popular open source flight controller software for DIY drones and UAV aircraft.
  There are some active members in the group that are also connected with the FOSS project on
  GitHub

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.

YouTube

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:

• Defining healthy communities
• Building healthy communities
• Community audits
• Dealing with toxic contributors
• Addressing mental health and burnout of moderators and community leads

Compose a guidebook chapter on the finer points of code migration. Topics may include:

• Identifying your code
• Classifing the code
• Code refactoring
• Update dependencies
• Documentation
• Public code repository
• Testing