Enablement is knowing how to start
Communication
- Can favor those in close proximity, the communication playing field may need to be leveled
- Providing context for distributed / time-shifted team members
- Providing context for future team members
- Eliminating tribal knowledge
- For communication to be open, you may need to develop psychological safety
Tribal knowledge
Questions:
How do we eliminate tribal knowledge? Where does the communication playing field need leveling? Do you need new tools, and practices to do so?
Discoverability:
- For something to be used, it needs to first be known
- This can be something as simple as giving repos meaningful / descriptive names, and ensuring the README.md file provides the essential information.
How to capture passive Documentation
- Conversations need to be documented in a written format
- Comments in a pull request
- Issues
- Slack conversations documented and discoverable
- Tagged emails
Contributor friction
- To maximize contributions, it needs to be easy for people to contribute without going through tedious and convoluted channels.
- To maximize merged contributions, it needs to be easy to review contributions.
What is a contributing guideline?
A contributing guideline provides discoverable documentation on how a contributor can contribute as well as formalizes the responsibilities of the developers accepting code changes into their project. These guidelines aren’t meant to be standardized throughout the entire organization, but the items below are recommended:
- Names of the trusted committers and their schedules (more on this in the - Trusted committer section)
- Must have information on contributing
- Code conventions
- Testing conventions
- Branching conventions
- Commit message conventions
- Steps for creating a good pull request
- How to submit feature requests
- How to submit bug reports
- How to submit issues
- How to contribute to the documentation
- Any dependencies
- Build-process schedule
- Sprint schedule
- Road map
GitHub’s Perspective
Some best practices we’ve discovered in the areas of communication, discoverability, reducing contributor friction have been the following:
- Adopt the practice of writing things down (Issues have largely replaced email)
- README, CONTRIBUTING, ISSUE / pull request templates, scripts to rule them all, profile repos
- Pull requests early and often
- Expose expertise through functional teams (few orgs, many teams)
- Automate review