The Mediation Manual

This short manual presents a small set of guidelines for Free and Open Source (FOSS) projects that should lead to a better perceived liveliness and progress. It targets programmers, maintainers and persons currently not involved in a project but willing to participate. The ideas presented here are no rocket-science and you decide on your own how much of it you want to adopt. The general idea is to have a special person - called mediator - who manages and takes care of the project's informations.

Motivation.

In Autumn 2004 I joined the GNU Classpath project which is a Free implementation of the Java class library. I have a good knowledge in Java and already sent patches to a few free software projects but was never involved in such an undertaking like Classpath. The project exists since 1998 and has a large amount of source code and numerous developers helped the effort so it was a bit hard for me to get into the game. A major stopper was that I did not know about the project's future plans, where work was needed and what design decisions have been made in the past. Additionally I found it unsatisfying asking questions which the next developer joining after me will ask again.

Soon I started thinking about a way to tackle this problem and how other projects as well could profit from my considerations. The result of that work is presented here.

How do I know that a mediator is a good idea for my project?

If your project has one of the following problems then a mediator might be the right person to add to your project:

• Only a small number of new developers are able to become members of the project because of the complexity of the codebase and their lack of understanding of the project's state.

• Active development is hindered because programmers do not really know what their peers are working on and how the puzzle parts fit together.

• Certain topics are discussed once in a while but no progress seems to take place in their regard.

• Lots of stuff was done, lots of stuff has still to be done but no one knows how far each and every piece has gotten and where it would be good to get started.

Why would I want to solve these problems?

The declared goal is to minimize these problems because such a situation can kill the members' motivation to invest time for their voluntary work. A developer may feel the work as cumbersome and then loses interest. The mediator is going to help the project to cope with these problems.

Why do you call the role "mediator"?

The term mediator is normally used in the context of conflict resolution and means the person who manages a conflict between affected parties. In the context of FOSS projects the conflict to manage is that certain persons have special knowledge or insight while others do not. My position is that it would be better for both parties if the knowledge gets more widespread.

Alright, so what is the mediator all about?

The mediator in a Free and Open Source Software project watches the communication inside a project and compiles the most essential bits and pieces into a concise form. This means that the mediator pays attention to mails and discussions on IRC even if he is not involved or directly affected by these.

An important aspect of his daily work is to look out for unfinished discussions or unanswered questions. Besides that the mediator should apply the 'newbie developer view' to find out what could be important for him. Finally finding out disparities like the big plan that comes up every there and then but was never done is a good trait.

Can you be more specific about what the mediator could actually do?

• Watch discussions
  Discussions that are held on mailing-lists are the ideal source for information that should be recorded. A mediator should watch all of them and decide which are relevant to be recorded. When the final word was spoken and a result is clear he should summarize the outcome and make it publicly available (for instance on a Wiki). It is a good idea to allow comments and modifications on the summaries because it is likely that somebody does not like the way it was written down. If a new discussion about the same topic arises it should be clear that the summary has to be updated.
• Find out when the same question is asked frequently.
  Recurring questions from users as well as fellow developers (especially newcomers) are no anomaly these days. What you could learn from them is that they indicate an informational gap that should be closed. If the question has not been answered satisfactory the mediator should look up relevant information from earlier discussions, write a question to the mailing list that displays the problem and its current state. If a result can be achieved that should be summarized and made public by the mediator.
• Identify information that is relevant for newbies.
  In order to make it easier for new developers the mediator should look out for information on coding guidelines or style and commit policies. Ideally these should be available in form of a file in the project folder as many projects do already. This way anyone working on the code has the style guidelines at hand.

Besides this the mediator should look out for implementation pitfalls like documentation that speaks contrarily to what is done in reality. The mediator should explain which variant is the right one and how one is supposed to cope with the problem.

In long-living projects it's likely that it carries a legacy because of an earlier design decision. Maybe there are two internal APIs having the same functionality and it's not clear for newcomers how to handle this. The best thing would be to deprecate and remove one of them but this is sometimes not (yet) possible and in the meantime new developers should be at least aware of the problem. Again that is something the mediator should look out for and describe the problem in a public summary.

• Find out fellow developers wishes.
  By reading emails of developers thoroughly you can often spot indications of wishes. These are sometimes expressed when someone fixed a problem but is not 100% comfortable with the current solution. The mediator should pay special attention to these utterances and get in contact with the developer to find out whether this aspect is important enough to get recorded. After the mediator made the idea publicly available others can review and/or tackle the problem.

Ok, but what about difficulties when doing the mediating?

It's clear that when interacting with people things do not always go round as easily as it should. There could be the problem that the mediator does not receive a real answer. If there is a lack of answers the topic might no be that relevant and the mediator should drop it. Then it's possible that the developers reach no compromise. In this case the mediator might summarize the opinions instead of a concise outcome.

Another problem is that a technical question might be to demanding for the mediator. In this case he should simply publish a draft summary and present it to the developers who know the topic better. If it's wrong there will be complaints and if it is too shallow others will ask for more information which the mediator can then add to reinforce the draft summary.

Can you give some practical examples for something a mediator has done?

Here are examples from the mediator's work at the GNU Classpath project.

Recurring question that was made available for newcomers afterwards

A developer who had seen the source code of Sun's Java class library is considered tainted and cannot work on the code in GNU Classpath because of the risk of copyright infringement claims. The FAQ contains a short entry that tells this but there was no other source of information. Newcomers asked whether they are tainted and if so what they could do instead of coding.

In one case a developer was already waiting for a definitive answer for about three months before he reminded the team of the issue. The mediator then send a mail, stating the problem (''What is a tainted developer allowed to work on”) and containing answers from earlier mails found in the archive, to the list. The topic was then discussed again and a comprehensive outcome was available later. The mediator then put a summary of the discussion in the Wiki.

Coding style disparity that was found and added to the newcomer's information

While working on the code the mediator noticed documentation tags which where not documented in the FAQ or the developer guidelines. At first the mediator used the tags as they seemed to be used without questioning their meaning. However after a while he found out that the tags are used differently depending on who edited a certain file. The situation was unclear and so he posed a question to the mailing-list. Although two developers answered the outcome was still not definite because they uttered contradictory. Nevertheless the mediator added a summary about the outcome of the discussion and put it in the Wiki. A few days later one of the developers had read that summary and complained about its content. After having had a small discussion on IRC with both developers the remaining bits could be solved and the summary was updated.

How much time does it require to be a mediator?

The person adopting this role decides on his own how much time is invested. It should be no fulltime job although the beginning might be an exception. The mediator should be supported by his fellow developers who provide him with information, answer questions and tell him occasionaly what is important information that should be recorded.

Why do you think the mediator should use a Wiki?

A Wiki is a really simple and powerful tool: It is to learn how to edit and everyone has equal rights when doing it. It can be used from nearly all Internet-connected computers and you get a version management for free. Finally if the current mediator leaves, somebody else can take up the work, without any need for new passwords etc.

How can I take action?

It depends on your status: If you are a maintainer or core developer you probably have enough work to do so that you do not want to take the mediator role yourself. That means you should find someone who want this job by filling a request form, adding a note to your project page or simply asking on your mailing list.

You should think about the technical requirements like installing a Wiki. Maybe you do not like a Wiki and instead use something else (e.g. letting mediator work on HTML pages in the repository).

Additionally the mediator should get to know where the important information will appear. Most projects use mailing lists but some have a Wiki instead, others rely heavily on IRC talk.

However if you are not yet involved with a project but would like to be then tell the projects maintainer or core group that you are willing to contribute as a mediator. Pointing them to this manual or using it as a base for your invitation mail is a good idea.

Are there any project characteristics that make it likely that a mediator will work?

• A team of voluntary developers and a big amount of sourcecode.
  The project should be typically community driven in contrast to enterprise driven. The latter might be more resistant against using what the mediator provides them. Besides that the mediator's effort is hindered if the project members have real-life meetings to make a design decision where he cannot attend.

Projects led by one developer are problematic because there is no communication between team members which the mediator could improve.

• Settled design phase.
  The history of the project should be long enough that design decisions are burrowed in the code. Furthermore due to developer fluctuation certain parts of the project may decay or bitrot because no one knows how these are done or understands them any more after certain developers left. Such a situation provides the informational gap which can be closed by the mediator.

References

• Visit GNU Classpath's mediation Wiki.
• The Linux kernel spawned several interesting projects which share the mediation idea:
  • kerneljanitors.org
  • kerneltraffic.org
  • kernelnewbies.org
• A janitor effort for Inkscape
• Subscribe to this manual's discussion mailing list or post directly.

This page is part of the ThesisFOSSIM.

This work is licensed under a Creative Commons License. -- RobertSchuster - 01 Mar 2005