[OASIS Issue Tracker] (TOSCA-270) Reverse ordering of presentation in YAML document

[OASIS Issues Tracker <workgroup_mailer@lists.oasis-open.org>]

Luca Gioppo created TOSCA-270:
---------------------------------

             Summary: Reverse ordering of presentation in YAML document
                 Key: TOSCA-270
                 URL: https://issues.oasis-open.org/browse/TOSCA-270
             Project: OASIS Topology and Orchestration Specification for Cloud Applications (TOSCA) TC
          Issue Type: Improvement
    Affects Versions: CSD06
            Reporter: Luca Gioppo


A.9 should become Chapter 4 and various A.x (where X<9) should go in logical prsentation ordering.
This way people that read the document after a really basic example like the "hello world" can start understanding the semantic of the notation and starting understanding the grammar and meaning of all the sections.
Is so logical to present ServiceTemplate as first than going deeper in the description of the child elements.
At the moment things are presented in reverse mode ... you get 32 pages of examples on a data structure you do not know (obviously you can infer something but ...)
Than you get namespaces and URI and for i.e. at line 1009 you get mentioned a capability and network_name, but you have not been introduced to them.
Generally we should avoid to use in the explanation terms that have not been yet explained to the reader otherwise it will not be easy to follow



--
This message was sent by Atlassian JIRA
(v6.2.2#6258)