View source for Dev:Wiki Documentation Guidelines


==Principles==
*Please, notice the basic Principles for joining this Wiki, as explained [[dev:How_to_join,_edit_and_create_the_railML_Wiki#Principles|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 {{rtm}}. 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 {{rml}} schema and its further development should be led in the {{site|https://www.railml.org/forum|forum|domain=forum}}. User questions can be placed in the forum or sent to {{site|https://www.railml.org/en/user/subschemes.html|the coordinators}}. For very complex issues concerning the Wiki, the forum can be the better place, too, rather than a Wiki discussion page.
*Employ the {{wiki2|:category:template|existing Wiki templates}} where applicable. In particular stick to the [[dev:Special_Wiki_Markup|markup guidelines]].
*As a privileged user, please review the changes continously; comp. {{wiki2|Help:Page validation}}.

==Terminology==
===Logo===
Please, use [[Template:rtm]] for displaying the {{rtm}} logo and analogously [[Template:rml]] for displaying the {{rml}} logo. <nowiki>{{rtm}}</nowiki> produces {{rtm}}. 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. <nowiki>[[dev:How to join, edit and create the railML Wiki|How to join, edit and create the {{rml}} Wiki]]</nowiki> for ''[[dev:How to join, edit and create the railML Wiki|How to join, edit and create the {{rml}} Wiki]]''.

===Key Words===
Please, employ the key words ''must'', ''must not'', ''required'', ''shall'', ''shall not'',
''should'', ''should not'', ''recommendended'', ''may'', and ''optional'' according to {{external|https://www.ietf.org/rfc/rfc2119.txt|RFC 2119}} (see {{wiki|Request for Comments}} to learn more about ''RFCs'', and {{external|https://www.cemconsultants.de/faq/Modale-Hilfsverben.pdf|CEN/CENELEC Rules of Procedure}}).
*'''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 {{wiki3|CO:tractionMode#Best_Practice_/_Examples|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 {{wiki|Help:Links|here|project=mw}}

There are several templates and adaptions in this Wiki that make it easier to set correct, standardized links under certain circumstances.
=== Links to {{rml}} elements and attributes ===
{{rml}} elements should generally be linked with [[Template:Tag]]. It minimally requires the subschema slug and the element name as arguments. For instance, <nowiki>{{tag|IS|infrastructure}}</nowiki> produces {{tag|IS|infrastructure}}.

Attributes can be linked with [[Template:Attr]] and [[Template:@]] respectively. For instance, <nowiki>{{@|id|wiki3:IS:infrastructure}}</nowiki> produces {{@|id|wiki3:IS:infrastructure}}.

=== Links between different {{rml}} Wikis ===
The {{rml|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 {{rml|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 {{rtm}} 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 {{site|https://railml.org|our website|mode=silent}}, please employ [[template:site]]. <nowiki>{{site|ttps://railml.org|our home page}}</nowiki> will bring you to {{site|https://railml.org|our home page}}.

For links to all kinds of {{wiki|Wikimedia|mode=silent}} projects, including {{wiki|Wikipedia|mode=silent}}, please use [[template:Wiki]]. <nowiki>{{wiki|File:RailML_headr.png|Our former logo at Wikimedia Wommons|project=commons}}</nowiki> will lead you to {{wiki|File:RailML_headr.png|Our former logo at Wikimedia Commons|project=commons}}.

For all other links, please employ [[Template:External]]. <nowiki>{{external|https://uic.org}}</nowiki> produces {{external|https://uic.org}}.

== 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<br>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 <nowiki>[[file:<file name>|x<height>]]</nowiki>, e.g. <nowiki>[[File:Example formula.png|x15px]]</nowiki> for [[File:Example formula.png|x15px]] — 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 <<nowiki />ref> tags. A documentation of <<nowiki />ref> tags can be found {{external|https://www.mediawiki.org/wiki/Help:Cite|at mediawiki.org}}. As to provide a uniform page structure, don't forget to add a section
:<nowiki>== References ==</nowiki>
containing the <<nowiki />references&nbsp;/> call.

=== References outside our Wikis ===
Within the [[#Footnotes|<<nowiki />ref> tags]], the references should be depicted in a standardized way using one of the folloging templates:
*[[Template:Site]] for links to {{site|http://railml.org|railml.org|mode=silent}} pages '''outside our Wikis'''.
*[[Template:External]] for external links (except for {{wiki|Wikimedia}} projects)
*[[Template:Wiki]] for links to Wikipedia and connected Wikimedia Projects like {{wiki|Wikibooks}} and {{wiki|Wikimedia Commons}}
*For Gitlab commits, use [[Template:Commit]].
*To reference {{rml}} 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 {{wiki|Help:Images|project=mw}}.

Please, respect other people's copyrights.

'''Within this Wiki:'''
*You can upload and include images without reference, if:
** the image belongs to {{rml|e.V.}}
** the owner explicitly made the image available for {{rml|e.V.}}
** the image belogns to the public domain or similar (e.g. {{external|https://creativecommons.org/publicdomain/zero/1.0/|CCO}})
*If you reference it correctly, you can upload and use images:
** Images that are explicitly licenced for {{rml|e.V.}} with obligation of reference
** Images under certain {{wiki|Creative Commons|Creative Commons licences}}:
:::{{tick}} {{external|https://creativecommons.org/licenses/by/4.0/|CC-BY}}
:::{{tick}} {{external|https://creativecommons.org/licenses/by-nd/4.0/|CC-BY-ND}}
::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:
::{{cross}} Without explicit permission
::{{cross}} Of unknown origin
::{{cross}} Share Alike licences, e.g. {{external|https://creativecommons.org/licenses/by-sa/4.0/|CC-SA}} in any combination
::{{cross}} Noncommercial licences, e.g. {{external|https://creativecommons.org/licenses/by-nc/4.0/|CC-NC}} in any combination
:A viable workaround is to offer a link to an image on the owners website. Please, avoid {{wiki|deep links}} directly to the image file like {{external|https://upload.wikimedia.org/wikipedia/commons/d/d5/Braunau_a_I%2C_Eisenbahnbr%C3%BCcke_nach_Simbach%2C_2.jpeg|in this example}}. Rather, link to a page that presents the file like {{external|https://commons.wikimedia.org/wiki/File:Braunau_a_I,_Eisenbahnbr%C3%BCcke_nach_Simbach,_2.jpeg|here}}.

==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 {{rml}}-Element should be addressed in the {{external|https://www.railml.org/forum/|forum}}.
* Let us share in your cordial nature.
===Formal Guideline===
*Start a new chapter for a new issue to discuss: <nowiki>===<Title of the issue>===</nowiki>
*Allways sign your contributions with <nowiki>—~~~~</nowiki> — 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.

{{interwiki|2=all}}
[[Category:GeneralDescription]]