This page describes what you should keep in mind when editing mediation related information. Whenever you decide to publish implementation details or outcomes of decisions and do not know how to organise things this page should help.

Index

Why guidelines?

Most humans feel comfortable if information is presented in some consistent and recurring way. That is why we having coding and documentation guidelines, too. Apart from that the metadata requirements for issues should help people finding information and the persons involved faster.

General layout

The FrontPage currently lists three distinct pages for collecting mediation information. It should be tried to keep most information directly as entries on those pages. However if you feel that a certain topic needs more space and should be granted a special page of its own you can do that as well. Furthermore if you think we should add another page that deals with another set of problems (apart from newbie information, decision information and current topics) feel free to contact me or set up the page yourself if you think that it will be OK. The main reason for keeping the number of pages low is that scattered information is more difficult to track and someone who is new to our system may feel lost.

Issue

Like in certain bug/patch tracking software and entry in the mediation system is called an issue. Each issue has several fields which are mandatory to fill out. The layout of the fields depends on whether the issue belongs to a collection page or has its own page.

Collection pages

As the name implies a collection page collects multiple issues and organises them. Pages of this type make use of the TableOfContents macro and the various types of headers. To add another entry to a collection page the easiest way is to copy an existing one and replace all the fields with their appropriate values. Additionally there is an issue template on each collection page which you can copy and fill out.

An issue is added to a collection page if itself and the outcomes can by described in few sentences. As a rule of thumb an issue on a collection page should not exceed three pages (I know that this depends on your screen size thats why its only a rule of thumb.).

Issue on its own

If you have decided to give an issue its own page please use the IssueOnItsOwnTemplate and fill out the respective fields. Such a page can then be linked from a collection page.

How an issue looks like

Eeach issue has at least three fields of mandatory metadata which is Last edit, Description and References. The fields help to structure the issues a bit without imposing too much formalism.

the same version of an issue.

Criticism

These guidelines on the style of issues are not carved in stone. Criticise them if you feel that they are too strict or something important is missing.

Hints

Please do not have discussions in the Wiki because these could not be tracked as easily as in the mailing list. If you find an issue controversial or need more clarification use our traditional communication channels.

Try not to break the general layout of the pages. If you have concerns about the current layout please get in contact with the current maintainer (see MediationMaintainerPage).

MediationEditingHints (last edited 2005-02-23 12:13:26 by brazzaville)