search

oasis-open / tosca-community-contributions

OASIS TC Open Repository: Manages TOSCA profiles, tests, and templates that are maintained by the TOSCA community. They are intended to be used as examples to help developers get started with TOSCA and to test compliance of TOSCA implementations with the standard.
https://github.com/oasis-open/tosca-community-contributions
Apache License 2.0
38 stars 25 forks source link

Placing glossary at the document start could make a new reader feel unwelcome #159

Open pmjordan opened 9 months ago

pmjordan commented 9 months ago

I was trying to read the csd6 as a new reader. The first item I come across is a glossary containg a number of similar, interrelated terms with no context. This may have the effect of making the document more complex than necessary. I suggest moving the glossary to the end of the overview section.

lauwers commented 9 months ago

What I would prefer to do instead is to beef up the metamodel section of the document. That section should clearly define the terms that are currently in the glossary. We may no longer need the glossary section if we have a strong metamodel section.

pmjordan commented 9 months ago

Fine, I just want to ensure the reader gets a gentle introduction.