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
Contents
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.
Last edit: Write the date and your savannah login name here. A last edit date makes it possible for people to make sure they are talking about
the same version of an issue.
Description: This is the main area of an issue. Write down as much clarifying information as you have for the topic.
Outcome: On the ClasspathDecisionsPage each issue has an extra field which summarizes the answers to a specific question. The separation into Description and Outcome makes it easier to find the result of a question when you do not need an introduction to the problem.
References: This part lists URLs to material that might be of interest to the topic. Often you will find references to emails in Classpath's mail archive here.
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).