Skip to content

Commit 278d5fd

Browse files
committed
Rephrase for clarity
1 parent 4541249 commit 278d5fd

File tree

1 file changed

+9
-8
lines changed

1 file changed

+9
-8
lines changed

documentation/modules/appendix/pages/best-practices.adoc

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -116,7 +116,7 @@ Complete identifier of such a Property: +
116116
`urn:samm:foo.myapplication:1.0.0#count`
117117
|===
118118

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`.
120120
So, the `foo` context (namespace) is already part of `count`​'s identifier.
121121

122122
[[no-redundant-suffix]]
@@ -340,7 +340,7 @@ For example, in German:
340340
|`erlaube Duplikate`
341341
|===
342342

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:
344344

345345
* To complete an orthographically correct sentence, e.g., in a pop-up message within a user interface. +
346346
(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
468468

469469
NOTE: Descriptions must be understandable without knowledge of SAMM.
470470

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.
472472
Users unfamiliar with SAMM might find the SAMM terminology confusing.
473473

474474
For example:
@@ -522,10 +522,11 @@ Avoid starting the Description with an article (where possible).
522522
[[triple-quotes]]
523523
=== Triple quotes in TTL file
524524

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.
527526

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.
529530

530531
See also: <<new-line>>.
531532

@@ -550,9 +551,9 @@ See also: <<new-line>>.
550551
Indent the Description content given within the triple quotes.
551552
See also <<triple-quotes>>.
552553

553-
Use the three-blank indentation of Turtle (TTL) files.
554+
Use the three-blank indentation of SAMM Turtle (TTL) files.
554555

555-
.Example: Keep the indentation
556+
.Example: Stick to the three-blank indentation
556557
[source,turtle,subs="attributes+,+quotes"]
557558
----
558559
:TrafficLight a samm-c:Enumeration ;

0 commit comments

Comments
 (0)