Home » railML newsgroups » railml.common » [railML3] Strategy of documentation at wiki.railML.org (Impulse for a discussion: how should railML3 be documented?)
[railML3] Strategy of documentation at wiki.railML.org [message #1415] |
Tue, 06 September 2016 13:08 ![Go to next message Go to next message](/forum/theme/default/images/down.png) |
Ferri Leberl
Messages: 24 Registered: September 2016
|
Junior Member |
|
|
Dear Everybody,
As the changes between versions 2.x and 3.x are considered to be big, DI Kolmorgen asked me to present some ideas on how we should deal with these differences in the documentation.
Essentially, there are two poles -- explaining the different versions within the same, existing wiki versus writing a new wiki from scratch -- and there might be some compromise by starting a new wiki, but importing certain existing content.
Besides this question, we ask you for ideas on how to standardize the documentation, and how to integrate UML or XML definitions into wiki pages.
I have enclosed a draft of the alternatives and their pros and cons. It is written in German. If it is required we will make up an English translation.
Thank you in advance for your interest and your ideas.
Yours,
Mag. Ferri Leberl
-
Attachment: impuls.pdf
(Size: 89.31KB, Downloaded 2710 times)
[Updated on: Tue, 06 September 2016 15:52] by Moderator Report message to a moderator
|
|
|
|
|
Re: [railML3] Strategy of documentation at wiki.railML.org [message #1450 is a reply to message #1421] |
Tue, 22 November 2016 14:42 ![Go to previous message Go to previous message](/forum/theme/default/images/up.png) ![Go to next message Go to next message](/forum/theme/default/images/down.png) |
Ferri Leberl
Messages: 24 Registered: September 2016
|
Junior Member |
|
|
Dear Readers,
Let me summarize the current state of work for the automatic wiki page generation. The process shall include the following steps:
- Extract essential information on each element (element name, element required/optional, element documentation, subschema, parent element, children, attributes, attributes required/optional, attributes documentation) from the XSD and collect it in a table
- Employ a script to build a wiki page for every line of the table (every element) as a starting point. These pages should be developed further manually and contain ...
- ... templates to include the essentials of the element. These template pages are generated with another, similar script, and they are not supposed to be changed and developed manually, but actualized with every change of the schema automatically.
I have meanwhile written scripts that solve the latter part of the path: employing the table to generate wiki pages for either purpose.
I ask you for help to solve the first part of the puzzle: reading the railML schema files and deriving a table presenting the structure of the XSD. These are the requirements for the table:
- The table should have one line for each element.
- The table should have, as mentioned above, a column for each element property we consider (element name, element required/optional, element documentation, subschema, parent element, children, attributes, attributes required/optional, attributes documentation).
- It should be a tab separated list, and where there may be several entries within a column (an element may have several children and several attributes), these entries should be separated by a semicolon.
Are there any obstacles we did not see?
Do you need any further information from our side?
Is there anybody in this forum who has the capacity to solve this part?
Thank you in advance for your opinions, your contributions and your help.
Yours,
Mag. Ferri Leberl
[Updated on: Mon, 28 November 2016 10:07] Report message to a moderator
|
|
|
|
Re: [railML3] Strategy of documentation at wiki.railML.org [message #1617 is a reply to message #1615] |
Tue, 27 June 2017 11:44 ![Go to previous message Go to previous message](/forum/theme/default/images/up.png) ![Go to next message Go to next message](/forum/theme/default/images/down.png) |
Ferri Leberl
Messages: 24 Registered: September 2016
|
Junior Member |
|
|
Dear All,
As the release of railML 3 approaches, I would like to revive the discussion about its documentation. Common understanding for railML.org will be a well documented first scheme version railML 3.1 with less room for interpretation than in the previous versions.
As mentioned in the last conferences railML 3 is going to be specified in UML.
Which changes will this bring for developers and users respectively?
Could this be a reason to shift the paradigm of the documentation? At the time being, the documentation is organized along elements. Should the element be the basic brick of the documentation of railML 3, too?
As I mentioned in my Impuls in #msg_1415 from September 6, 2016, templates help to standardize content but are difficult to edit. A compromise might be to use wiki templates to describe an element but to expand them as soon as the basics are laid down, as to realize both a high degree of standardization and an easy way to edit. The drawback would be that it would be difficult to change the general structure later on.
What is your opinion towards this tradeoff?
Is there a desire to switch the content management system (CMS)? I assume, that we will rely on MediaWiki also in future because of its low entry hurdle, but there should be room to discuss alternatives if you suggest any.
Thank you in advance for your ideas.
Yours, Ferri Leberl
|
|
|
Re: [railML3] Strategy of documentation at wiki.railML.org [message #1626 is a reply to message #1617] |
Thu, 20 July 2017 16:32 ![Go to previous message Go to previous message](/forum/theme/default/images/up.png) |
Ferri Leberl
Messages: 24 Registered: September 2016
|
Junior Member |
|
|
Dear all,
As I have mentioned earlier, the workflow should be first to extract an element list from the schema, and then, at second, to transform the element list into wiki code.
DI Wunsch provided us an XSLT-script that transforms a railML-document into code suitable for the MediaWiki-extension "Tree and Menu". Principally, it should be possible to change this script such, that, if you feed it with a "complete" railML-file, containing all elements, with all attributes, exactly once, it builds the element list needed for step two. This would be a second best alternative for step one. It would not deliver all required information (particularly the documentation tags would be lost), but it would provide a base.
Is there an efficient way to produce such examples in XMLSpy or Oxygen?
Thank you in advance for hints, heuristics, and examples.
Yours,
Mag. Ferri Leberl
|
|
|
Goto Forum:
Current Time: Sun Aug 25 01:13:04 CEST 2024
|