Is your task related to a problem? Please describe.
Description in aspect models follow different convention: some add complete sentences, some use glossary style etc. To have a better consistency across models it would be helpful to have some recommendations how to do it.
Is your task related to a problem? Please describe. Description in aspect models follow different convention: some add complete sentences, some use glossary style etc. To have a better consistency across models it would be helpful to have some recommendations how to do it.
Describe the solution you'd like
Extend https://eclipse-esmf.github.io/samm-specification/snapshot/appendix/best-practices.html with chapter for how to write a good element description
Also add rules for how to create a good display name
add reference to rules for names because it might not be clear to all that there are also rules that are mandatory to be followed
Rules should include the following:
depending on language:
for English always start with small letter in German as used in dictionary, for nouns capital letter, for verbs small letter
Do not start with preferred name "the <...>
no complete sentence
do not use abbreviations in description, only if known very widely
formulate description such that it would be a good tool tip
formulate description such that is could be the definition in an IEC/ISO glossary
If additional information needed for explanation add (numerated) notes
If additional examples needed for explanation add (numerated) examples with captial letter "EXAMPLE", if only one example then no number
If see-Attribute information not sufficient add source information
Do not use brand names or other proper names in descriptions
if other properties are mentioned in the description use the preferred name, not the display name or name
Do not mention the SAMM Class, like "Characteristic", "Trait" etc. Imagine that it can be used in a completely different modelling language
For Display names:
depending on language:
for English always start with small letter in German as used in dictionary, for nouns capital letter, for verbs small letter