Dev:How to edit and contribute to the Wiki

From railML 3 Wiki
Jump to navigation Jump to search
This wiki should be supporting the development of railML®-schemes. It allows users to create new content and edit existing articles, and setup a comprehensive knowledge database to the railML® standard.
Mit Hilfe dieses Wikis (externer Link, 🇩🇪) soll der Einstieg in die Entwicklung der railML®-Teilschemen erleichtert werden. Es ermöglicht den Benutzern neue Inhalte zu schaffen, sowie vorhandene Beiträge zu bearbeiten und damit eine umfassende Wissensdatenbank zum railML®-Standard aufzubauen.

Introduction

This platform serves as a central hub for information and collaboration. To maintain a thriving and collaborative environment, we have established these guidelines to help users understand how to join, contribute and edit content. railML® is an open-source data exchange standard specifically tailored for railway applications. It includes railML® 2, railML® 3 as well as railML® Ontology, which facilitates interoperability and data exchange between different rail systems and applications. Additionally, RailTopoModel® provides frameworks and models for representing railway infrastructure and operations in a standardized manner.

Principles

Our Wiki is built on the following principles:

  • We adhere to an authenticity policy, requiring users to register with their real names. This promotes transparency and accountability within our community.
  • Writing privileges are granted only to registered users. The registration procedure is explained below. If you decide not to register, we would still appreciate your feedback via e-mail.
  • Edits will undergo review, which users can locate under ‘Pending changes’ label, to ensure the accuracy and quality of the information shared.
  • When contributing to the Wiki, prioritise clarity and user-friendly language to enhance the understanding of railway software operations for users with varying levels of understanding.
  • All information added to the Wiki should be backed by citeable sources whenever possible. This ensures that the information presented is reliable and can be verified by others.
  • Contributions should be neutral and free from bias. Avoid promoting specific tools or companies and strive to present information objectively.
  • Aim to provide information that is applicable and relevant across different countries and regions. Avoid references or details specific to a particular country's regulations or practices unless it is necessary for context and strive to keep the content relevant to a general audience.

By following these principles, we can collectively build a robust knowledge base that reflects the values and standards of our community while ensuring the understandability and integrity of railML®.

How to register to the Wiki

To contribute to the railML® Wiki, you need to register on the website railML.org and request a Wiki account. Preference for writing privileges is given to experienced users from our registered partners, with whom we seek to build long-term collaborative working relationships. To join, please follow these steps:

  • Visit the following link https://www.railml.org/en/registration.html and complete the registration process.
  • Send an e-mail to our coordinator from your company business e-mail. Additionally, you may include information about your motivation and experience with railML® schemas in the e-mail.
  • The coordinator will review your request and provide you with a separate Wiki account.
  • Log in to https://railml.org (link to the railML® website) using your e-mail (account). Once logged in, you can navigate to the Wiki section from the website and start contributing to the railML® Wiki.
  • Please note that the system will automatically switch to the Wiki page for editing. If not, click on ‘Log into railml.org’ on the Wiki page, log out and log in again to ensure your account is active for Wiki contributions. We also recommend checking your browser and cookie settings if necessary.
  • As a logged-in user, you can set the interface language according to your preference.

How to contribute

As a registered user on the railML® Wiki, you have the possibility to contribute and help improve our documentation. We encourage active participation and contributions from all members. Before contributing, familiarise yourself with existing content to avoid duplication.

The principles of editing a wiki are explained here (external link).

Please, stick to our common templates to allow for a standardized documentation. Some essential templates are explained on railML® markup templates. Especially, employ template:external for external links.

Preview of editing before saving the changes

Edit a page

If you want to change or extend some content on a specific railML® element page, do the following:

  1. Ensure you are logged in as a registered user on the website railml.org. If not, follow the provided steps to register.
  2. Go to the respective railML® Wiki page you want to edit. If login issues persist, refer to the steps outlined above.
  3. Click on ‘Edit’ to begin changes. ‘Edit’ button typically allows you to edit the content of an element page within a visual editor for general cases. However, when working with railML®, we use extensive markup templates. Thus the ‘Edit’ button limits you to open the template editor and modify parameters in the source editor within it.
  4. ‘Edit source’ button, on the other hand, takes you to the Wiki markup or Wiki text editor where you can edit the underlying code that generates the page’s layout and formatting. This is useful for making more complex changes or for contributors who prefer working with markup directly.
  5. Use the “Preview” feature. Look for a button labelled “Show Preview” within the editing interface. This option is typically located between “Submit changes” and “Show changes” button. Click on this to see how your edits will appear once published, without actually making the changes live on the Wiki. Here you can see the example of a preview after you edit.
  6. Please refrain from editing “Documentation” section of the railML® 3 wiki as this will be overwritten by the automatic transfer from the XSD documentation to the Wiki.
  7. We highly encourage users to focus their efforts on the “Introduction”, “Best Practice/Examples” or “Additional Information” sections. This area is important for seeking practical advice and real-world applications of railML®. You can see the best practice under this Wikipage:
  8. Alternatively, use the search option to find relevant subschema pages.
  9. If you have difficulty editing the page and it displays or mentions ‘Mirror’, it indicates that the content resides on another railML® Wiki. To edit the desired page, simply navigate to the appropriate Wiki installation - railML® 2 or railML® 3 respectively.
  10. Respect others’ contributions. Discuss proposed changes in the appropriate railML forum (link to the railML® website) before editing. Engage in discussions on railML® forum to share ideas, ask questions and provide feedback as well.
  11. Before finalising, perform a ‘Preview’ to catch any potential issues. Ensure template parameters and closing brackets are accurate.
  12. Describe your changes in the ‘Summary’ section to provide context.
  13. Submit your changes by clicking ‘Save’. Confirm that your changes are satisfactory. Address any surprises, especially regarding template parameters.
  14. Your contribution is complete. Thank you for enhancing railML® documentation.

If you are uncertain about the changes you have made, do not hesitate to reach out railML® for a review and feedback. In case your edits get reverted (external link), please understand that is our part of review process. We appreciate your dedication to enhancing the railML® Wiki community!

Adjust the XML tree

  1. Go to the XML tree wiki page
  2. Press "Edit" or Bearbeiten
  3. Crawl to the right position in the railML® tree
    Instead of scrolling there, it's easier to "search" for the parent element
  4. Insert a new element with a new line at the appropriate position, if necessary
    Only insert one line for each different element no matter how often it may occur at this certain position in the XML instance document.
    • Start with the appropriate number of stars "*" indicating the depth in the XML tree.
    • Choose the appropriate element documentation page deploying the link in angle brackets
    • Add all possible attributes deploying the Attribute template, separated by comma
      The inherited ones come at least (that's for some quick validation purposes of this page, that may be roughly generated by an XQuery search)
      No matter, if the attributes are optional or mandatory.
    example:
    ***{{TT:Tag|train}} {{Attr|type}}, {{Attr|trainNumber}}, {{Attr|additionalTrainNumber}}, {{Attr|scope}}, {{Attr|processStatus}}, {{Attr|id}}, {{Attr|code}}, {{Attr|name}}, {{Attr|description}}, {{Attr|xml:lang}}
    
  5. Describe your changes with "Summary" or Zusammenfassung
  6. Check your changes with "Preview" or Vorschau
    Adjust the page text where needed
  7. Submit your changes with "Save" or Speichern
  8. Done. Thank you for your contribution.

Start a new railML® Wiki page for a new railML® element

The documentation paradigm of railML® 2 and railML® 3 differ fundamentally. Therefore,the processes will be described separately, beginning with railML® 3. In railML® 3, new element pages are generated automatically. They will contain default chapters. Feel free to add content.

🗒️
NOTICE
Don't remove or expand template:robot!  
🗒️
NOTICE
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

 


Support

We appreciate your interest to contribute to the railML® wiki and will try to support you.

  • A documentation for the mediawiki sofware which is the basis of this wiki can be found here (external link).
  • Please, follow our Wiki Documentation Guidelines.
  • Questions referring to the use of this wiki are welcome on the discussion page.
  • Please, act responsibly with contacting the webmaster (webmaster ät railml dot org).