The importance of shared understandings
In his book Where in the world is my team, Terence Brake outlines the three challenges that global and virtual teams face. There is Isolation (reduced contacts and difficulty of trust building can easily make you feel alone and lose motivation), Fragmentation (unclear purpose and fuzzy responsabilities fragment your effort and make you inefficient) and Confusion (too much or too little information makes you take the wrong path, and hidden activities prevent anyone from noticing).
As virtual and global aggregations of common interests, community-driven open source projects are specifically vulnerable to those challenges. Fortunately, Brake also explains how to fight these. One of the areas he identified is convergence, through shared understandings, as a way to generate clarity and fight confusion (and, to a lesser extent, fragmentation).
Without shared understandings, the lack of shared context, the conflicting assumptions, and the distance between team members can generate a lot of confusion. This confusion results in the loss of everyone's time in the best case, in team implosion in the worst. With shared understandings, you get natural convergence and you reduce the need for interrupt-driven communication.
That's why we, the OpenStack team, need documentation. Not only user-oriented and developer-oriented documentation, but also project documentation. The team already has a clear mission. Meeting face-to-face during our design summits allows us to get to know each other, which is critical to bootstrap common context. We need to ensure we have team principles (we have design tenets and coding standards, we need a code of conduct), clear priorities, open implementation plans, shared performance indicators... This won't happen in a day.
Since I joined the project, I tried to produce a basic set of reference documents which should help generating clarity. So far I concentrated on our release cycle and our Launchpad tools:
Sometimes it looks like those project documentation pages are spelling the obvious, but that's the price to pay to make sure everyone doesn't have different assumptions. Those wiki pages are very much open for discussion and evolution: the goal is not to force anyone into new workflows or extra bureaucracy. The goal is to have a clear reference point when you need more clarity. I hope it will help avoiding confusion by establishing shared understandings.