Home » railML newsgroups » railml.misc » [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
Ferri Leberl is currently offline  Ferri Leberl
Messages: 7
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 83 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 #1420 is a reply to message #1415] Thu, 15 September 2016 13:17 Go to previous messageGo to next message
Dirk Bräuer is currently offline  Dirk Bräuer
Messages: 187
Registered: August 2008
Senior Member
Dear Ferri Leberl,

thank you for your Diskussionsanstoß for documentation of railML 3
from my side. I can follow your problem description and suggestions.

I personally would prefer solution 3 "Recycling" but I am not sure
whether this may mean an effort still too high. I possibly would follow
this solution if there is a possibility to "recycle step by step",
leaving a current topic on-line until it is recycled. All existing
information should always stay available, better in an old contents
(railML 2.x) than not at all.

Concerning "Schemeneinbindung", I understand the problem but do not have
enough experience to suggest anything. I can only offer some possible
help by programming a kind of tool which parses and converts xsd files
into a file format which can possibly better be handled by existing
tools. The question would be whether this solution would have any
advantages over "Einbindung von HTML" - probably not. Anyway, at least
it could be a solution for "Entfernung des Kopfes und Umwandlung von
Links". Please do not hesitate to contact me if you feel that I can help
in this direction.

With best regards,
Dirk Bräuer.

P.S.: Please do not MIME-encode attachments in forum posts. There are
news readers (as mine) which do not decode them and present them
in-line. Better provide a download link.
Re: [railML3] Strategy of documentation at wiki.railML.org [message #1421 is a reply to message #1415] Thu, 15 September 2016 15:59 Go to previous messageGo to next message
Bob Janssen is currently offline  Bob Janssen
Messages: 3
Registered: March 2016
Junior Member
Dear all,

Up to Present, the wiki contains information generated by the XSD editing tool XMLspy - great.

Now, we're using Enterprise Architect. This tool lets us write UML which is much richer than XSD schemata. In fact, UML registers documentation, both graphically and textually. The information is far richer than what XMLspy can capture.
It stands to reason that we make Enterprise Architect generate the HTML-information that we publish on the site. EA allows us to tailor the HTML-output and this is where Herr Leberl comes in: I suggest that he do the tailoring so that EA produces appealing HTML.

Please refer to http:// www.sparxsystems.com/enterprise_architect_user_guide/12.1/re port_generation/htmlreport.html for more information about the templating that EA can do. I would suggest that he create some templates.

Yours,
Bob Janssen
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
Ferri Leberl is currently offline  Ferri Leberl
Messages: 7
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

Previous Topic: Announcement of support termination for railML 2.0 and 2.1 schemes
Next Topic: [railML3] Development progress
Goto Forum:
  


Current Time: Mon May 01 08:18:19 CEST 2017