Dev:Wiki Structuring Guidelines: Difference between revisions
[unchecked revision] | [checked revision] |
(→Paragraphs Hand Pages: @Semantics) |
(→Purpose: Warnung) |
||
(6 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 page explains, how to structure an element documentation page within {{wiki3}}. 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]]. | ||
==Purpose== | ==Purpose== | ||
Element pages in | Element pages in {{wiki3}} are being created with a system of templates, notably {{wiki3|Template:DocBase}} and {{wiki3|Template:Schemaexport}}. Employing these templates grants for a standardized design. The templates specify the paragraphs of element pages. Please, enter the relevant information for the element in the designated paragraphs of {{wiki3|Template:DocBase}} 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 | *This structure sets a frame for the {{site|https://www.railml.org/en/developer/certification.html|certification|inlang=silent}}. | ||
{{note|Don't remove or expand {{wiki3|template:robot}}!|error}} | |||
{{note|Don't edit the automatically maintained version pages! | |||
These pages contain [[template:Schemaexport]] and their pagenames end with a version number, e.g.: ''/3.1''|error}} | |||
==Structure | ==Structure== | ||
In the {{rml|3}} wiki, element pages are created via GWPS<ref name=gwps>GWPS = Gruschwitz' Wonderful Python Script</ref>. GWPS will for each element create a ''hand page'' that is supposed for content created by the wiki authors (best practice, notes etc) and a ''robot page'' that contains information directly retrieved from the schema and that the wiki authors should generally not touch. The robot page will be framed within the hand page. | In the {{rml|3}} wiki, element pages are created via GWPS<ref name=gwps>GWPS = Gruschwitz' Wonderful Python Script</ref>. GWPS will for each element create a ''hand page'' that is supposed for content created by the wiki authors (best practice, notes etc) and a ''robot page'' that contains information directly retrieved from the schema and that the wiki authors should generally not touch. The robot page will be framed within the hand page. | ||
===Paragraphs ''Hand Pages''=== | ===Paragraphs ''Hand Pages''=== |
Latest revision as of 16:05, 3 April 2023
Structuring Guidelines for Element Pages
Focus
This page explains, how to structure an element documentation page within The railML® 3 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.
Purpose
Element pages in The railML® 3 wiki are being created with a system of templates, notably Template:DocBase and Template:Schemaexport. Employing these templates grants for a standardized design. The templates specify the paragraphs of element pages. Please, enter the relevant information for the element in the designated paragraphs of Template:DocBase 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® 3 wiki, element pages are created via GWPS[1]. GWPS will for each element create a hand page that is supposed for content created by the wiki authors (best practice, notes etc) and a robot page that contains information directly retrieved from the schema and that the wiki authors should generally not touch. The robot page will be framed within the hand page.
Paragraphs Hand Pages
Hand pages are created by GWPS[1] with Template:DocBase (which will be expanded by creation). Template:DocBase creates the following paragraphs:
- Introduction:
- Shall contain a short introduction.
- 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®.
- Documentation:
- Container for subchapters Syntax, Semantics and (possibly) Semantic Constraints.
- This paragraph should not be edited manually, except within the subparagraphs Semantics and Semantic Constraints.
- Syntax:
- Here the robot pages are being framed.
- Do not edit manually!
- Certification: Compliance with the description in the Wiki is relevant for fulfilling the requirements (see below).
- Semantics:
- Shall contain the semantics (meaning, compare semantics (
)) of elements and attributes as well as semantic constraints.
- Generally speaking, this paragraph is a backup, as the semantics should be recorded within the schema and presented under #Syntax. Still it may be necessary for clarifications, for missing documentation within the schema and off course for semantic constraints.
Example: in <requiresSwitchInPosition> the semantics is explained within the schema as the reference to any switch in the overlap required to be in a particular position and its position and @mustOrShould as the level of enforcement. - This paragraph is developed by the railML® community.
- Should only state the meaning of the element respectively attribute.
- No rules or explanations should be presented here. Concise remarks like “not to be confused with” are allowed, if they narrow down the meaning.
- 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. There will be special attention on the obedience of semantic constraints.
- Shall contain the semantics (meaning, compare semantics (
- Best Practice / Examples:
- Shall contain best practice; national rules and peculiarities; 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®.
- Additional Information:
- Container for subchapters Notes and Open Issues.
- This paragraph should not be edited manually, except within the subparagraphs Notes and Open Issues.
- 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®.
- Open Issues:
- Shall contain open discussions and unsolved problems.
- 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®.
Paragraphs Robot Pages
Robot pages are created by GWPS[1] with Template:Schemaexport.
Certification: Compliance with the description in the Wiki is relevant for fulfilling the requirements.