Dev:Wiki Documentation Guidelines

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 are welcome, but should not deliver additional content. Please, employ Template:Deu for German content, as to make the languages distinguishable at first glance.
• This documentation should describe the currently supported versions of RailTopoModel^®. 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 (link to the railML^® website). User questions can be placed in the forum or sent to the coordinators (link to the railML^® website). For very complex issues concerning the wiki, the forum can be the better place, too, rather than a wiki discussion page.
• Employ the existing wiki templates where applicable. In particular stick to the markup guidelines.
• As a privileged user, please review the changes continously; comp. Help:Page validation.

Terminology

Logo

Please, use Template:rtm for displaying the RailTopoModel^® logo and analogously Template:rml for displaying the railML^® logo. {{rtm}} produces RailTopoModel^®. 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. [[dev: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.

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, and CEN/CENELEC Rules of Procedure (external link)).

• 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.

Lists and enumerations

For attribute lists and value lists, please use concise language. Make enumerations rather than using complete sentences, as to avoid redundancies.

Language standards

• The wiki shall be written in British English
• Chapter- and page titles should be written with capital initials as here.
• Redirects to pages from alternative spellings should be avoided. Please, don't set a redirect e.g. from topo:RTM Modelling Concepts from topo:RTM modelling concepts or topo:RTM Modeling Concepts.

Entering Links

A general outline on using links in Mediawiki can be found here ()

There are several templates and adaptions in this wiki that make it easier to set correct, standardized links under certain circumstances.

Links to railML^® elements and attributes

railML^® elements should generally be linked with Template:Tag. It minimally requires the subschema slug and the element name as arguments. For instance, {{tag|IS|infrastructure}} produces <infrastructure>.

Attributes can be linked with Template:Attr and Template:@ respectively. For instance, {{@|id|wiki3:IS:infrastructure}} produces @id.

Links between different railML^® Wikis

The railML^® 2 wiki has the interlanguage prefix railml2 and the interwiki prefix wiki2. As to avoid errors on mirroring, please, employ Template:Wiki2 whenever possible.

The railML^® 3 wiki has the interlanguage prefix railml3 and the interwiki prefix wiki3. As to avoid errors on mirroring, please, employ Template:Wiki3 whenever possible.

The RailTopoModel^® wiki has the interlanguage prefix wikirtm and the interwiki prefix topo. As to avoid errors on mirroring, please, employ Template:Topo whenever possible.

For interlanguage links, please, employ template:interwiki as to avoid errors on mirroring.

Links beyond our Wikis

For links to our website, please employ template:site. {{site|ttps://railml.org|our home page}} will bring you to our home page (link to the railML^® website).

For links to all kinds of Wikimedia projects, including Wikipedia , please use template:Wiki. {{wiki|File:RailML_headr.png|Our former logo at wikimedia commons|project=commons}} will lead you to Our former logo at wikimedia commons ().

For all other links, please employ Template:External. {{external|https://uic.org}} produces https://uic.org (external link).

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. [[File:Example formula.png|x15px]] for — the x states, that the 15 points are the height rather than the width; 15px fits well into the line height.

Citations and References

Footnotes

Please, reference sources in footnotes rather than in the running text. Footnotes can be generated with <ref> tags. A documentation of <ref> tags can be found at mediawiki.org (external link). As to provide a uniform page structure, don't forget to add a section

== References ==

containing the <references /> call.

References outside our wikis

Within the <ref> tags, the references should be depicted in a standardized way using one of the folloging templates:

• Template:Site for links to railml.org pages outside our wikis.
• Template:External for external links (except for Wikimedia () projects)
• Template:Wiki for links to Wikipedia and connected Wikimedia Projects like Wikibooks () and Wikimedia Commons ()
• For Gitlab commits, use Template:Commit.
• To reference railML^® tickets, use Template:Ticket.
• To reference sources without weblinks (e.g. books), use Template:Source.

Images

A general outline how to include images in mediawiki can be found at Help:Images ().

Please, respect other people's copyrights.

Within this wiki:

• You can upload and include images without reference, if:
  • the image belongs to railML^® e.V.
  • the owner explicitly made the image available for railML^® e.V.
  • the image belogns to the public domain or similar (e.g. CCO (external link))
• If you reference it correctly, you can upload and use images:
  • Images that are explicitly licenced for railML^® e.V. with obligation of reference
  • Images under certain Creative Commons licences ():

✔ CC-BY (external link)

✔ CC-BY-ND (external link)

For displaying the references of a CC-licenced image Template:CC may be helpful. You might find it convenient to enter the reference in Template:Licence.

• Please, do Not upload or include images:

✘ Without explicit permission

✘ Of unknown origin

✘ Share Alike licences, e.g. CC-SA (external link) in any combination

✘ Noncommercial licences, e.g. CC-NC (external link) in any combination

A viable workaround is to offer a link to an image on the owners website. Please, avoid deep links () directly to the image file like in this example (external link). Rather, link to a page that presents the file like here (external link).

Use cases

The railML^® wiki offers a number of Use Cases.

A Guideline to implementing Use Cases can be found under Dev:Use cases.

Examples

In contrast to railML^® 2, railML^® 3 is not supposed to be backward compatible. As a consequence, Examples may be relevant for one version only. Please, always make clear, to which version an example applies!

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.