Dev:Wiki Documentation Guidelines

From wiki.railML.org
Jump to: navigation, search

Principles

  • Please, notice the basic Principles for joining this wiki, as explained here
  • The working language of this wiki is English. The complete content should be covered in English. Translations in German and French are welcome, but should not deliver additional content. Please, employ Template:Deu for German content and Template:Fra for french content, as to make the languages distinguishable at first glance.
  • This documentation should describe the currently supported versions of railML®. Please, neither describe obsolete versions (that are not any longer supported), nor describe future features.
  • The discussion pages are designated for issues about this wiki. Any discussions concerning e.g. the railML® schema and its further development should be led in the forum. User questions can be placed in the forum or sent to the coordinators. For very complex issues concerning the wiki, the forum can be the better place, too, rather than a wiki discussion page.

Terminology

Please, use Template:rml for displaying the railML® logo. {{rml}} produces railML®. It is consens, that the initial letter r should allways be written small, and that the superscript ® should always be displayed. Both is granted for by the template. Don't use the superscript ® in URLs — such links cannot be processed! Instead, use railML in the URL and employ the vertical bar | to display an appropriate link text, e.g. [[How to join, edit and create the railML wiki|How to join, edit and create the {{rml}} wiki]] for How to join, edit and create the railML® wiki.

Schema

Please, use the term schema rather than scheme and the plural form schemas rather than schemata.

The term schema denotes the complete railML® XML schema.

The schema has four subschemas: Timetable, Rollingstock, Infrastructure and Interlocking.

Key Words

Please, employ the key words must, must not, required, shall, shall not, should, should not, recommendended, may, and optional according to RFC 2119 (external link) (see wikipedia (external link) to learn more about RFCs).

  • Must (also: required, shall, have to) denotes an absolute requirement.
  • May: (also: optional) denotes a true optionality. An implementation must interoperate with any other implementation independent of whether either of the implementations employs the option except for the feature the option provides.
  • Must not (also: shall not) denotes an absolute prohibition.
  • Should (also: recommended) means that a course is not required, but the full implications must be understood before choosing a different course.
  • Should not (also: not recommended) means that a course is not prohibited, but the full implications must be understood before choosing that course.

Edit element documentation pages

The railML® wiki should document the actual state of railML®.

Please, describe only elements that already exist! Don't start articles about elements that are only in discussion or in development! You can start describing new elements as soon as they are part of a release candidate version of railML®.

The core of this wiki are pages documenting single railML® elements. The framework for such pages is provided by template:ElementDocu. Please, stick to it as to ensure a corporate layout.

In most cases the element documentation sites are already defined. If not, have a look at the Developers Guide for new element documentation sites.

Start a new railML Wiki page for a new railML element

Allways use Template:ElementDocu to grant for a uniform presentation of railML®-elements. An explanation of the procedure can be found here.

In special cases, you can employ a template that is based on Template:ElementDocu as to inherit certain data. Read here, how to do so.

Adjust the XML tree

We offer the readers an XML-Tree on page CO:XMLtree.

Whereever the structure of railML changes with a new release (new or depricated elements and/or attributes), the tree should be actualized.

An instruction on how to edit the tree can be found here.

Enter mathematical Formulas

This wiki does not offer you a math mode. Therefore you should insert formulas as graphics:

  • Create the formula e.g. with a word processor; save it as a graphic
    If you use an online formula editor, please be aware of the terms of use. You do it at your own liability.
  • Upload it via the page Special:Upload
  • Insert it with [[file:<file name>|x<height>]], e.g. <nowiki>[[File:Example formula.png|x15px]] for Example formula.png — the x states, that the 15 points are the height rather than the width; 15px fits well into the line height.

Discussion Pages

All Wiki Pages have a discussion page which is linked at the top of the page. There, all matters concerning the page can be discussed.

Dos & Don'ts

  • Please, use this page to discuss issues of the referring article
  • Please, don't discuss the object of the article here. Questions, suggestions etc. about e.g. a certein railML®-Element should be addressed in the forum (external link).
  • Let us share in your cordial nature.

Formal Guideline

  • Start a new chapter for a new issue to discuss: ===<Title of the issue>===
  • Allways sign your contributions with —~~~~ — the four tildas will be replaced automatically with your user name and a time stamp
  • If you answer somebody, show this by indenting the text. You can set indents with colons (:) at the start of the line. Allways use one colon more than the person you are answering.
Example: Two colons (::) to indent this line towards the line above.