Collaboration

This page describes a concept which is part of our glossary

The content of this article requires cleaning up to meet OD's quality standards. Check the wiki best practices for guidelines on improving article and categorisation quality.

In the wiki environment, collaboration is a term which comes up often in conversation, but what exactly does it mean in the wiki context? After using the wiki for a couple of years there have been a lot of examples of a group of two or more of us collaborating on certain creative endeavours, some of them have gone well and lead to completion, some have got off to a good start, and yet others have failed to get off the ground at all.

The technical aspects if an efficient collaboration system have been defined and are slowly being implemented in the form of wiki extensions such as the workflow extension. Further down the track we intend to develop these ideas into a more ideal structure within the nodal environment.

Aside from these developments, I think it's important to address some more fundamental aspects of collaboration which would be part of the MediaWiki Workshop and of other documents such as charter, manifesto, help and best practices. These aspects of collaboration are described in the following sections.

Shared vision and responsibility

Define shared vision and expectations: this needs to be done regardless of scale. It could be a simple document or trivial programming excercise, or it could be an entire application. Either way the collaborators must have clearly defined what they all expect from the result to be and what parts they're each playing in achieving this.

An important point to note when it comes to defining shared vision is that it must be defined in terms of the roles and processes available otherwise there is no path available to the organisation that can lead to the vision.

Another important issue with shared vision is diversity. In the book The fifth discipline the concept of an organisation's ability to "harmonise diversity" is introduced (on page 228). In the context of collaborative systems this ability translates as analysing the commonality of the diverse views of the shared visions and "forking" smaller groups which work together on sub-visions which are defined from the differences they have to the master vision. The original group of all members continue to collaborate on the aspects which are shared amongst all visions.

Turn taking

Of course one major phase of collaborating on anything is the actual day-to-day chipping away of the work, but there's an important aspect of this which needs to be made explicit and in many cases would even benefit from being formalised with categorisation. It is the concept of turn taking which describes the aspect of conversation whereby only one person talks at a time and the focus (the person currently talking) changes from person to person (for more detail about this concept see conversation analysis).

The wiki environment is not a normal free-flowing conversation, but rather is a blackboard system where the focus moves amongst the roles working on a thread of work (such as an article or some code). Each work session performed by a role involves becoming familiar with the state which has changed since the last time they worked on it, and then using their expertise to refine any aspects which now need attention. After doing this the role will either consider the job to be complete and notify the other team members, or will see that further feedback from other members is required. Categorisation and workflow tools can aid in the organisation of notifying members that their feedback is required.

It's important for all members to be very clear about this aspect of collaboration, because I've found this to be one of the main ways in which stagnation occurs. For example, I'm sure every seasoned wiki user is familiar with the feeling of talking with friends or colleagues about an idea they all share a common interest in, and then deciding together to start an article outlining the goals clearly so they can begin working together on it only to find that after one or two edits it completely stagnates never to move again. I believe a major reason for this common occurrence is that one or more of the members don't realise an unspoken fact: it's their turn to apply their expertise. If they were all working with the turn-taking context in mind they'd see from their watch-list, or from the changes that some significant work had been done over some time period and would realise the expectation that a different member must now commit time to a session of work on it for it to progress and to fuel the collaborative effort and keep it rolling. If there's many threads under way then todo lists and categorisation cat easily be employed to avoid forgetting which threads of work are in need of a particular role's attention.

Template:Collab

Template:Collab has been created to clarify which articles these collaboration principles apply to, so that even if specific workflow or role-based categorisation is not defined for the article, it can at least be made clear that it is an article for which the turn-taking principles of collaboration are expected.

Merging is the key to software developer collaboration

From Mark Shuttleworth's thoughts - Tuesday, June 19th, 2007

Continuing my discussion of version control tools, I’ll focus today on the importance of the merge capability of the tool.

The “time to branch” is far less important than the “time to merge”. Why? Because merging is the act of collaboration - it’s when one developer sets down to integrate someone else’s work with their own. We must keep the cost of merging as low as possible if we want to encourage people to collaborate as much as possible. If a merge is awkward, or slow, or results in lots of conflicts, or breaks when people have renamed files and directories, then I’m likely to avoid merging early and merging often. And that just makes it even harder to merge later.

The beauty of distributed version control comes in the form of spontaneous team formation, as people with a common interest in a bug or feature start to work on it, bouncing that work between them by publishing branches and merging from one another. These teams form more easily when the cost of branching and merging is lowered, and taking this to the extreme suggests that it’s very worthwhile investing in the merge experience for developers.

In CVS and SVN, the “time to branch” is low, but merging itself is almost always a painful process. Worse, merging a second time from another branch is WORSE, so the incentives for developers to merge regularly are exactly the wrong way around. For merge to be a smooth experience, the tools need to keep track of what has been merged before, so that you never end up redoing work that you’ve already solved. Bzr and Git both handle this pretty well, remembering which revisions in someone else’s branch you have already integrated into yours, and making sure that you don’t need to bother to do it again.

When we encourage people to “do their own thing” with version control, we must also match that independence with tools to facilitate collaboration.

Now, what makes for a great merge experience?

Here are a couple of points:

• Speed of the merge, or time it will take to figure out what’s changed, and do a sane job of applying those changes to your working tree. Git is the undisputed champion of merge speed. Anything less than a minute is fine.
• Handling of renames, especially renamed directories. If you merge from someone who has modified a file, and you have renamed (and possibly modified) the same file, then you want their change to be applied to the file in your working tree under the name YOU have given it. It is particularly important, I think, to handle directory renames as a first class operation, because this gives you complete freedom to reshape the tree without worrying about messing up other people’s merges. Bzr does this perfectly - even if you have subsequently created a file with the same name that the modified file USED to have, it will correctly apply the change to the file you moved to the new name.
• Quality of merge algorithm. This is the hardest thing to “benchmark” because it can be hugely subjective. Some merge algorithms take advantage of annotation data, for example, to minimise the number of conflicts generated during a merge. This is a highly subjective thing but in my experience Bzr is fantastic in merge quality, with very few cases of “stupid” conflicts even when branches are being bounced around between ad-hoc squads of developers. I don’t have enough experience of merging with tools like Darcs which have unusual characteristics and potentially higher-quality merges (albeit with lots of opportunity for unexpected outcomes).

I like the fact that the Bazaar developers made merging a first-class operation from the start, rather than saying “we have a few shell scripts that will help you with that” they focused on techniques to reduce the time that developers spend fixing up merges. A clean merge that takes 10 seconds longer to do saves me a huge amount of time compared to a dirty (conflict-ridden, or rename-busted) merge that happened a few seconds faster.

Linus is also a very strong advocate of merge quality. For projects which really want as much participation as possible, merge quality is a key part of the developer experience. You want ANYBODY to feel empowered to publish their contribution, and you want ANYBODY to be willing to pull those changes into their branches with confidence that (a) nothing will break and (b) they can revert the merge quickly, with a single command.

See also

• Sharing
• Wiki organisation
• Web3.0