Better Documentation inside schemas

Need for better short documentation inside code

What is needed?

Developers, which come in contact with railML schemas, should be enabled to understand the intention of railML elements and attributes without searching for help from wiki, forum or otherwise.

They should find a brief summary of railway specific use of elements and attributes.

That should not be the repetition of elements' or attributes' names, but one or two sentences about the use in real railway transit.

This comment could be in English and German for easier understanding with less language inaccuracy.

How to implement?

This comment should use the XMLSchema components:

<xs:annotation>
    <xs:documentation>
        ...
    </xs:documentation>
</xs:annotation>

This structure enables further use through scripts and other tools to generate a brief documenation.

This comment should not be an XML comment like this:

<!-- -->

Where is a detailed documentation?

Nevertheless, the wiki documentation works as detailed help platform with coordinators' and users' contribution:

http://wiki.railml.org

(Notice by members of 16th meeting in Brunswick, October 6th, 2009)