Dev:Wiki Structuring Guidelines

From railML 2 Wiki
Revision as of 15:45, 6 April 2020 by RailML Coord Documentation (talk | contribs) (New page)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Structuring Guidelines for Element Pages
 

Focus

This page explains, how to structure an element documentation page within this 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 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:

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

Paragraphs

Template:ElementDocu creates the following paragraphs:

  • Position of XYZ in the XML-Tree:
    • Shall contain the position of the element in the XML tree
    • railML® 2: generated manually by the coordinator straightforward from the schema; no manual additions
    • railML® 3: generated automatically by GWPS; no manual additions
    • Criteria to be fulfilled for successful certification
  • Multiplicity: straightforward from the schema – relevant for certification
  • 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
  • Attributes: No rules or explanations. Concise remarks like “not to be confused with” are allowed, if they explain the intention – not relevant for certification
  • Syntactic constraints: straightforward from the schema – relevant for certification
  • Semantic constraints:relevant for certification
  • Best Practice Examples: for instance national rules and peculiarities; Code examples – not relevant for certification
  • Open Issues: open discussions and unsolved problems – not relevant for certification
  • Notes: Anything that does not fit into other paragraphs – not relevant for certification