You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: documentation/modules/appendix/pages/best-practices.adoc
+9-8Lines changed: 9 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -116,7 +116,7 @@ Complete identifier of such a Property: +
116
116
`urn:samm:foo.myapplication:1.0.0#count`
117
117
|===
118
118
119
-
NOTE: The complete identifier of a Property is the versioned namespace concatenated with the element's `name`, for example, `urn:samm:foo.myapplication:1.0.0#count`.
119
+
NOTE: The complete identifier of a Property is the versioned namespace combined with the element's `name`, for example, `urn:samm:foo.myapplication:1.0.0#count`.
120
120
So, the `foo` context (namespace) is already part of `count`​'s identifier.
121
121
122
122
[[no-redundant-suffix]]
@@ -340,7 +340,7 @@ For example, in German:
340
340
|`erlaube Duplikate`
341
341
|===
342
342
343
-
*Rationale* By using words the same way they would be listed in a dictionary, the `preferredName` attribute is flexible to be used in further applications, for example:
343
+
*Rationale:* By using words the same way they would be listed in a dictionary, the `preferredName` attribute is flexible to be used in further applications, for example:
344
344
345
345
* To complete an orthographically correct sentence, e.g., in a pop-up message within a user interface. +
346
346
(The Preferred Name can be *used as-is*.)
@@ -468,7 +468,7 @@ SAMM model element terms like Entity, Property, Aspect, etc. do not belong in th
468
468
469
469
NOTE: Descriptions must be understandable without knowledge of SAMM.
470
470
471
-
*Rationale* An Aspect Model may be converted to a different output format or modeling language in which SAMM model elements are unknown.
471
+
*Rationale:* An Aspect Model may be converted to a different output format or modeling language in which SAMM model elements are unknown.
472
472
Users unfamiliar with SAMM might find the SAMM terminology confusing.
473
473
474
474
For example:
@@ -522,10 +522,11 @@ Avoid starting the Description with an article (where possible).
522
522
[[triple-quotes]]
523
523
=== Triple quotes in TTL file
524
524
525
-
For those working with Aspect Models as Turtle (TTL) files, reading Descriptions along one long line does not help to grasp a Description's meaning.
526
-
In addition, long lines hide content far beyond the screen width, which makes it difficult to skim through TTL files.
525
+
Use the TTL triple quotes operator to mark the Description as a section with line breaks.
527
526
528
-
Therefore, use the TTL triple quotes operator to mark the Description as a section with line breaks.
527
+
This avoids having long Descriptions sitting on just one line.
528
+
529
+
Description sections with line breaks are easier to be grasped for human readers when skimming through TTL files.
529
530
530
531
See also: <<new-line>>.
531
532
@@ -550,9 +551,9 @@ See also: <<new-line>>.
550
551
Indent the Description content given within the triple quotes.
551
552
See also <<triple-quotes>>.
552
553
553
-
Use the three-blank indentation of Turtle (TTL) files.
554
+
Use the three-blank indentation of SAMM Turtle (TTL) files.
0 commit comments