Dev:Wiki Structuring Guidelines: Difference between revisions

From railML 2 Wiki
Jump to navigation Jump to search
[checked revision][checked revision]
(New page)
 
No edit summary
 
(8 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{head|Structuring Guidelines for Element Pages}}
{{head|Structuring Guidelines for Element Pages}}
==Focus==
==Focus==
This page explains, how to structure an element documentation page within this wiki.
This page explains, how to structure an element documentation page within {{wiki2}}. A General outline for contibuting to this wiki can be found [[Dev:Wiki Documentation Guidelines|here]]. If you want to ''start'' contributing to this wiki, please begin with [[Dev:Wiki Documentation Guidelines|this outline]].


A General outline for contibuting to this wiki can be found [[Dev:Wiki Documentation Guidelines|here]].
Currently ({{timestamp|15:29, 7 April 2020 (CEST)}}) not all parts of the {{rml|2}} wiki contain all descriptions in the correct section. Please be indulgent and support us in maintaining the Wiki.<br/>{{deu|Derzeit enthalten nicht alle Teile des {{rml|2}} Wikis alle Beschreibungen im richtigen Abschnitt. Bitte seien Sie nachsichtig und unterstützen Sie uns bei der Pflege des Wikis.}}


If you want to ''start'' contributing to this wiki, please begin with [[Dev:Wiki Documentation Guidelines|this outline]]
==Purpose==
==Purpose==
Element pages in this wiki are being created with [[Template:ElementDocu]]. Employing this template grants for a standardized design. The template specifies the paragraphs of element pages. Please, enter the relevant information for the element in the designated paragraphs according to the rules set below. This clearcut structure serves two aims:
Element pages in {{wiki2}} are being created with template {{wiki2|Template:ElementDocu}}. Employing this template grants for a standardized design. The templat specifies the paragraphs of element pages. Please, enter the relevant information for the element in the designated paragraphs according to the rules set below. This clearcut structure serves two aims:
*It helps users to find relevant information
*It helps users to find relevant information.
*This structure sets a frame for the [[dev:Certification|certification]]
*This structure sets a frame for the {{site|https://www.railml.org/en/developer/certification.html|certification|inlang=silent}}.
==Paragraphs==
 
[[Template:ElementDocu]] creates the following paragraphs:
==Structure==
In the {{rml|2}} wiki, element pages are made by hand with {{wiki2|Template:ElementDocu}}.
 
{{wiki2|Template:ElementDocu}} creates the following paragraphs:<br>(But some of them only, if used)
*'''Position of ''XYZ'' in the XML-Tree:
*'''Position of ''XYZ'' in the XML-Tree:
**Shall contain the position of the element in the XML tree  
**Shall contain the position of the element in the XML tree.
** {{rml}} 2: generated manually by the coordinator straightforward from the schema; no manual additions
** Generated manually by the coordinator straightforward from the schema. Please do not edit.
** {{rml}} 3: generated automatically by ''GWPS''; no manual additions
** ''Certification: Compliance with the description in the Wiki is relevant for fulfilling the requirements.<br/>{{deu|Zertifizierung: Die Übereinstimmung mit der Beschreibung im Wiki ist relevant für eine Erfüllung der Vorgaben.}}''
** ''Criteria to be fulfilled for successful certification''
*'''Multiplicity:'''
*'''Multiplicity:''' straightforward from the schema – '''relevant for certification'''
**Shall contain the element [[dev:Multiplicity|multiplicity]].
*'''Semantics:''' Only the intention. No rules or explanations. Concise remarks like “not to be confused with” are allowed, if they explain the intention – '''not relevant for certification'''
** Generated manually by the coordinator straightforward from the schema. Please do not edit.
*'''Attributes:''' No rules or explanations. Concise remarks like “not to be confused with” are allowed, if they explain the intention – '''not relevant for certification'''
** ''Certification: Compliance with the description in the Wiki is relevant for fulfilling the requirements.<br/>{{deu|Zertifizierung: Die Übereinstimmung mit der Beschreibung im Wiki ist relevant für eine Erfüllung der Vorgaben.}}''
*'''Syntactic constraints:''' straightforward from the schema – '''relevant for certification'''
*'''Semantics:'''
*'''[[dev:Semantic Constraints|Semantic constraints]]:''' – '''relevant for certification'''
** Shall contain the element semantics.<br>(the meaning of an element, compare {{wiki|semantics}}).
*'''Best Practice Examples:''' for instance national rules and peculiarities; Code examples – '''not relevant for certification'''
** Example: {{wiki2|IS:balise#semantics|<balise>}} is defined as ''a single balise and its attributes, where a balise is an electronic beacon or transponder placed between the rails of a railway as part of an Automatic Train Protection (ATP) system.''
*'''Open Issues:''' open discussions and unsolved problems – '''not relevant for certification'''
** This paragraph is developed by the {{rml}} community.
*'''Notes:''' Anything that does not fit into other paragraphs – '''not relevant for certification'''
** Should only state the meaning of the element.
**No rules or explanations should be presented here. Concise remarks like “not to be confused with” are allowed, if they narrow down the meaning.
** ''Certification: Compliance with the description in the Wiki is relevant for fulfilling the requirements.<br/>{{deu|Zertifizierung: Die Übereinstimmung mit der Beschreibung im Wiki ist relevant für eine Erfüllung der Vorgaben.}}''
*'''Attributes:'''
** Shall contain the attribute semantics.<br>(the meaning of an attribute, compare {{wiki|semantics}}).<br>The attribute semantics will usually refer to the respective element semantics and explain, how the attribute can influence the meaning of the element.
** Example: {{wiki2|IS:balise#dir|<balise>@dir}} explains, that a balise may be relevant only for one direction.
** This paragraph is developed by the {{rml}} community.
** Do not place rules or explanations here. Concise remarks like “not to be confused with” are allowed, if they narrow down the meaning.
** ''Certification: Compliance with the description in the Wiki is relevant for fulfilling the requirements.<br/>{{deu|Zertifizierung: Die Übereinstimmung mit der Beschreibung im Wiki ist relevant für eine Erfüllung der Vorgaben.}}''
*'''Syntactic constraints:'''
** Shall contain syntactic constraints set within the schema.
** Generated manually by the coordinator straightforward from the schema. Please do not edit.
** ''Certification: Compliance with the description in the Wiki is relevant for fulfilling the requirements.<br/>{{deu|Zertifizierung: Die Übereinstimmung mit der Beschreibung im Wiki ist relevant für eine Erfüllung der Vorgaben.}}''
*'''[[dev:Semantic Constraints|Semantic constraints]]:'''
** Shall contain [[dev:Semcon|semantic constraints]].
** Semantic constraints should be added only by the subschema coordinator or in reconcilement with him (the procedure is explained [[Dev:Semantic_Constraints#How_to_introduce_Semantic_Constraints|here]]).
** ''Certification: Compliance with the description in the Wiki is relevant for fulfilling the requirements.<br/>{{deu|Zertifizierung: Die Übereinstimmung mit der Beschreibung im Wiki ist relevant für eine Erfüllung der Vorgaben.}}''
*'''Best Practice/Examples:'''
**Shall contain best practices; national rules and peculiarities as well as code examples.
** This paragraph is developed by the {{rml}} community.
** ''Certification: This information is not directly relevant for compliance with the specifications and is intended to assist in understanding {{rml}}.<br/>{{deu|Zertifizierung: Diese Angaben sind nicht direkt relevant für eine Erfüllung der Vorgaben und sollen beim Verständnis von {{rml}} unterstützen.}}''
*'''Open Issues:'''
** Shall contain open discussions and unsolved problems. Not to be used as discussion board (use {{site|https://forum.railML.org}} instead; links to the forum discussion are welcome) nor as ticket system (use {{ticket|3=the ticket system}} instead; links to tickets are welcome).
** This paragraph can be edited by the {{rml}} community.
** ''Certification: This information is not directly relevant for compliance with the specifications and is intended to assist in understanding {{rml}}.<br/>{{deu|Zertifizierung: Diese Angaben sind nicht direkt relevant für eine Erfüllung der Vorgaben und sollen beim Verständnis von {{rml}} unterstützen.}}''
*'''Notes:'''
** Shall contain anything that does not fit into other paragraphs.
** This paragraph is developed by the {{rml}} community.
** ''Certification: This information is not directly relevant for compliance with the specifications and is intended to assist in understanding {{rml}}.<br/>{{deu|Zertifizierung: Diese Angaben sind nicht direkt relevant für eine Erfüllung der Vorgaben und sollen beim Verständnis von {{rml}} unterstützen.}}''
 
<references />
{{interwiki}}

Latest revision as of 16:02, 3 April 2023

Structuring Guidelines for Element Pages
 

Focus

This page explains, how to structure an element documentation page within The railML® 2 wiki. A General outline for contibuting to this wiki can be found here. If you want to start contributing to this wiki, please begin with this outline.

Currently (April 2020) not all parts of the railML® 2 wiki contain all descriptions in the correct section. Please be indulgent and support us in maintaining the Wiki.
Derzeit enthalten nicht alle Teile des railML® 2 Wikis alle Beschreibungen im richtigen Abschnitt. Bitte seien Sie nachsichtig und unterstützen Sie uns bei der Pflege des Wikis.

Purpose

Element pages in The railML® 2 wiki are being created with template Template:ElementDocu. Employing this template grants for a standardized design. The templat specifies the paragraphs of element pages. Please, enter the relevant information for the element in the designated paragraphs according to the rules set below. This clearcut structure serves two aims:

  • It helps users to find relevant information.
  • This structure sets a frame for the certification.

Structure

In the railML® 2 wiki, element pages are made by hand with Template:ElementDocu.

Template:ElementDocu creates the following paragraphs:
(But some of them only, if used)

  • Position of XYZ in the XML-Tree:
    • Shall contain the position of the element in the XML tree.
    • Generated manually by the coordinator straightforward from the schema. Please do not edit.
    • Certification: Compliance with the description in the Wiki is relevant for fulfilling the requirements.
      Zertifizierung: Die Übereinstimmung mit der Beschreibung im Wiki ist relevant für eine Erfüllung der Vorgaben.
  • Multiplicity:
    • Shall contain the element multiplicity.
    • Generated manually by the coordinator straightforward from the schema. Please do not edit.
    • Certification: Compliance with the description in the Wiki is relevant for fulfilling the requirements.
      Zertifizierung: Die Übereinstimmung mit der Beschreibung im Wiki ist relevant für eine Erfüllung der Vorgaben.
  • Semantics:
    • Shall contain the element semantics.
      (the meaning of an element, compare semantics (Wiki banner.png)).
    • Example: <balise> is defined as a single balise and its attributes, where a balise is an electronic beacon or transponder placed between the rails of a railway as part of an Automatic Train Protection (ATP) system.
    • This paragraph is developed by the railML® community.
    • Should only state the meaning of the element.
    • No rules or explanations should be presented here. Concise remarks like “not to be confused with” are allowed, if they narrow down the meaning.
    • Certification: Compliance with the description in the Wiki is relevant for fulfilling the requirements.
      Zertifizierung: Die Übereinstimmung mit der Beschreibung im Wiki ist relevant für eine Erfüllung der Vorgaben.
  • Attributes:
    • Shall contain the attribute semantics.
      (the meaning of an attribute, compare semantics (Wiki banner.png)).
      The attribute semantics will usually refer to the respective element semantics and explain, how the attribute can influence the meaning of the element.
    • Example: <balise>@dir explains, that a balise may be relevant only for one direction.
    • This paragraph is developed by the railML® community.
    • Do not place rules or explanations here. Concise remarks like “not to be confused with” are allowed, if they narrow down the meaning.
    • Certification: Compliance with the description in the Wiki is relevant for fulfilling the requirements.
      Zertifizierung: Die Übereinstimmung mit der Beschreibung im Wiki ist relevant für eine Erfüllung der Vorgaben.
  • Syntactic constraints:
    • Shall contain syntactic constraints set within the schema.
    • Generated manually by the coordinator straightforward from the schema. Please do not edit.
    • Certification: Compliance with the description in the Wiki is relevant for fulfilling the requirements.
      Zertifizierung: Die Übereinstimmung mit der Beschreibung im Wiki ist relevant für eine Erfüllung der Vorgaben.
  • Semantic constraints:
    • Shall contain semantic constraints.
    • Semantic constraints should be added only by the subschema coordinator or in reconcilement with him (the procedure is explained here).
    • Certification: Compliance with the description in the Wiki is relevant for fulfilling the requirements.
      Zertifizierung: Die Übereinstimmung mit der Beschreibung im Wiki ist relevant für eine Erfüllung der Vorgaben.
  • Best Practice/Examples:
    • Shall contain best practices; national rules and peculiarities as well as code examples.
    • This paragraph is developed by the railML® community.
    • Certification: This information is not directly relevant for compliance with the specifications and is intended to assist in understanding railML®.
      Zertifizierung: Diese Angaben sind nicht direkt relevant für eine Erfüllung der Vorgaben und sollen beim Verständnis von railML® unterstützen.
  • Open Issues:
    • Shall contain open discussions and unsolved problems. Not to be used as discussion board (use https://forum.railML.org (link to the railML® website) instead; links to the forum discussion are welcome) nor as ticket system (use the ticket system instead; links to tickets are welcome).
    • This paragraph can be edited by the railML® community.
    • Certification: This information is not directly relevant for compliance with the specifications and is intended to assist in understanding railML®.
      Zertifizierung: Diese Angaben sind nicht direkt relevant für eine Erfüllung der Vorgaben und sollen beim Verständnis von railML® unterstützen.
  • Notes:
    • Shall contain anything that does not fit into other paragraphs.
    • This paragraph is developed by the railML® community.
    • Certification: This information is not directly relevant for compliance with the specifications and is intended to assist in understanding railML®.
      Zertifizierung: Diese Angaben sind nicht direkt relevant für eine Erfüllung der Vorgaben und sollen beim Verständnis von railML® unterstützen.


Retrieved from "https://wiki2.railml.org/index.php?title=Dev:Wiki_Structuring_Guidelines&oldid=14702"