in a conversation recently, it occurred to me that i have a whole set of assumptions about transparency and openness, which are really norms of collaborative open source software development. so i thought it would be useful to be more explicit about these expectations, and why i think they are important.

the main goal of these norms is to make it easier for people to participate in a project, have access to resources so they can review them when it’s convenient for them, and generally feel welcome participating. they don’t prevent conflict, of course — but in my experience they make it easier to resolve conflicts effectively, by gathering more input and clearly documenting decisions and the reasoning behind them. some of these are specific to software development, but most would apply to any collaboration where people need to have meetings, make decisions, produce documents, etc.

resources

  • project resources, such as meeting agendas/notes, reports, and documentation, should be public, and barriers to editing should be as low as possible. this makes it easy to find the resources, link to them, and contribute to them.
  • for source code, this should be a source code management tool, and preferably one with a large community of users like github (to increase the number of people who can easily participate). but even a less popular tool or a self-hosted tool will provide features for browsing, commenting, and reviewing.
  • for documents, this could be a wiki, google drive, etc. a tool that lets people edit in place is better than a tool where you have to use some other system to update things, since it lowers barriers to participation.
  • mailing lists and chat rooms should be public so anyone can join, and anyone can browse the archives. this makes it easier to participate in discussions, and to refer to past discussions for context.
  • for projects that involve change management, there should be a public issue tracker. for software, this should be github issues, jira, or some other software-oriented issue tracker (because they provide a ton of software-specific features). this could also be a project management tool for non-software projects, or even a list of suggested changes in a document. the important part is to make it easy to suggest changes and clearly document decisons.

process

  • meetings should be public to make it easy for people to participate in decision-making. depending on the size, this can be a google hangout or other video call, or a conference call, or a scheduled chat time.
  • meeting agendas should be posted in advance so people can decide whether they are interested in participating, and notes should be posted afterwards to document decisions so they can be referred to later.
  • the more important a decision, the more effort should be made to gather input and foster discussion. this includes posting to the mailing list asking for input, discussing the topic in meetings, scheduling special meetings (and/or meetings at relevant conferences) to give people the most opportunity to notice that the decision is being made, and have input.
  • for source code changes, using pull requests are an important way of providing feedback, and making it clear what changes are being proposed. they also allow people to comment and discuss the changes with reference to specific code changes.

mindset

  • gather use cases and work from concrete examples, which helps incorporate different points of view.
  • involve people before things are finalized, so their concerns can be addressed when it’s easy to make changes. this is much better than finishing something in isolation and then releasing it to others, since it gives their input greater weight.
  • periodically review your processes, and be open to changes that improve the ability of other to participate.
  • be welcoming of new participants and contributors, and pay special attention when they report trouble participating or finding information, or don’t feel welcome to participate. explictly documenting norms of behavior and participation guidelines (e.g., a code of conduct) can help make it clearer how to participate.