Draft – 02/15/2005

Introduction

This short manual presents small set of guidelines for 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 wanting to do something. The ideas presented 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 who manages the project's informations. The workload for this person should be low enough to do that besides coding.

Problems

This paragraph presents the characteristics a project should have for the guidelines to have an effect.

A team of voluntary developers and a big amount of sourcecode.

The project should be typically community driven. That means the developers participate out of personal interest. Furthermore the codebase should be big enough that arrangements and decision-making between the developers is necessary in other words it should be non-manageable by a single-person.

A project structure with no or few formal regulations

The project should not have strict commit policies or regulations that control the way developers work on the project. A good counter-example is the GNOME project which has strict release policies and schedules.

A long history (at least one year).

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 bitrot because no one knows how its done or understands these parts.

The problems a suitable project should facing are:

New developers are distracted because of the complexity of the codebase and their 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.

Goal

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. We are going to do that by making it possible for everyone to find out where work is done, where it has to be done and ideally where it was done. Along the lines we will build and maintain a guide for newcomers.

Realisation

The main work of this task is to be done by someone who is called the mediator. The term mediator is normally used in the context of conflict resolution and means the person who manages a conflict between affected parties. However mediation consists of tasks that are of interest for FOSS projects, too. These tasks are clarification of issues and helping people communicating with each other.

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 its fellow developers who provide him with information and answer questions.

General working style

The mediator should regard information management as really important for the project. This means that he should pay attention to mails and discussions on IRC even if he is not involved or directly affected by these.

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

However if you feel this is too much for you then lower the standards and do the things where you feel more comfortable.

Specific tasks

I will now describe specific actions a mediator can do. Read them to find out which of them might be applicable for your project.

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. 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 same question is asked frequently.

e.g. questions by non-members/users

find relevant information

summarize the problem and re-discuss it

add outcome

identify information that is relevant for newbies

that is

coding guidelines/style, commit policies

implementation pitfalls (doc speaks contrary to what is done in reality)

legacy of former design decisions

summarize this and make it public

keep it up to date

find out when fellow developers utter wishes

discuss whether this should be recorded

allows others to review the idea

allows others to tackle the idea

develop and care project documentation

coding guidelines

a FAQ

Examples:

usage of a Wiki:

simple usage, easy to learn and edit

puts no one in superior positions (equal rights on modification)

automatic version management

usable from a wide range of computer (supposition: web is ubiquitous)

maybe: input form adjustable for mediator work (eg. TwikiForms)

newbie information+frequently asked: tainted developer

newcomers ask whether they are tainted and what they could do else

FAQ entry exists but does not make situation clear

one developer was still waiting for a definitive answer (~3 months]

question was brought up again, no immediate answer

mediator recalled situation

found earlier question in mailing-list archive

found earlier answers to the question

summarized and worded a new question containing references to the information found

comprehensive answer was available later

put summary of the answer in a Wiki

if no real answer:

lack of answers: question may be not relevant

no compromise: summarize the opinions

if technical question to demanding:

get in contact with the people who know

try a summary and present it to them

if its wrong there will be complaints

if its too shallow others will ask for more information

add specifics then

newbie information+noticed while working+unclear situation: special documentation tags

while working, noticed special documentation tags

not documented in FAQ or developer guidelines

used as they seem to be used without questioning their usage

found more of them, usage seemed unclear

posed question on mailing-list to clarify situation

answers available but still not clear

summarized first draft and put in Wiki

received feedback upon entry by a developer on IRC: summary seemed not complete

solved immediately by asking involved persons

summary updated

Depending on what your relationshiup and interests you can do the following

If maintainer or core developer:

is project suitable?

interest to the topic?

find someone who has

write a request form (sourceforge and savane allows this) or add a note to your project page

consider technical requirements: Wiki

consider project specifics:

Are you using IRC?

Are your discussions Wiki-based?

etc. pp.

If interested individual:

is there a project where you can work on?

mail the developers about you plan. are there suggestions?

Success: You do not need to apply all of these guidelines. Its is a success for me if you have started thinking about that topic at least. Maybe its starts to bother you too sometime.

2005-02-07T14:12:02