SAF-documentation improvements (proposals)

[Harald-Vogel]

When working with SAF by using the documentation on git as modeling guide, there might come up proposals for better formulation, navigation, wording, image displaying, missing information, linking, etc. All this shall be collected here for consideration to support the documentations quality.
Additionally, some comments or proposals for improvements may indicate a misunderstanding or the proposal is already available or was not found intuitively.

[haarer]

Good Morning Harald,
thanks for the proposal, i like the idea.

[Harald-Vogel]

Some proposals for improvements:

• https://github.com/GfSE/SAF-Specification/tree/TdSE2023:
  Headlines like "Operational Domain Aspect Context" should become aligned with the wording in the grid to "Operational Domain Aspect Context&Exchange"
• Is it possible to get the SAF-Grid larger displayed when clicking on it? It is for me a central point for navigation and decission making how to go on e.g. in view selections. The resolution is quite low so the grid is hard to read.
• As Example: On Page "SAF User Documentation : Operational Capability Viewpoint", (https://github.com/GfSE/SAF-Specification/blob/TdSE2023/viewpoints/Operational-Capability-Viewpoint.md) see figure: There are aggregations used but the stereotype is "SAF_OperationalCapabilityComposition". This is confusing and makes a big difference for me.

[clalitsc]

Done, headline aligned with grid ... Operational Domain Aspect Context & Exchange

[clalitsc]

Operational Capability Viewpoint: I need to able to express on one hand a composition and on the other hand an aggregation relations between different operational capabilities. We will have to add the option of an aggregation relationship. BTW, we have the same issues in our functional domain, system capability viewpoint.

[clalitsc]

Harald,

which SAF grid would you like as high resolution file? The concept viewpoint grid, or the FFDS example view grid?

[Harald-Vogel]

My SAF entry point is this page: https://github.com/GfSE/SAF-Specification/tree/TdSE2023
There is the SAF Viewpoint Grid displayed and below the grid the objectives and the links to the appropriate views. Both elements, the grid and the links to the views becomes a helpful unit for navigation and understanding. If one this elements is not sufficient for easy navigation it frustrates quite quickly especially for SAF beginners. For documentation purposes this page is good enough but for guiding purposes my request would improve this page. Please check, if my request can be applied to other pages I have not seen so far.

[clalitsc]

Harald, our aim is to document viewpoints from a systems engineering point of view [acceptably well]. An argumentation of navigation completeness is not our purpose. How to know, how to measure when the frustration starts about an element not sufficiently well designed for easy navigation? A change of perspektive to adopt to a SAF beginner is not easy to achieve. We would have to do interviews with different SAF beginners. Quite a challenge, a valuable one, no question. /Christian

[Harald-Vogel]

Ok, so, shall I keep on going with my proposals or shall I stop. For me it is not a problem and I would absolutely not become piqued about it.

[clalitsc]

Harald, please keep going. You put spotlights on some of our blind spots.

[Harald-Vogel]

happy to oblige!

[haarer]

Am 8. Dezember 2023 07:51:47 MEZ schrieb Harald Vogel ***@***.***>:

My SAF entry point is this page: https://github.com/GfSE/SAF-Specification/tree/TdSE2023 There is the SAF Viewpoint Grid displayed and below the grid the objectives and the links to the appropriate views. Both elements, the grid and the links to the views becomes a helpful unit for navigation and understanding. If one this elements is not sufficient for easy navigation it frustrates quite quickly especially for SAF beginners. For documentation purposes this page is good enough but for guiding purposes my request would improve this page. Please check, if my request can be applied to other pages I have not seen so far. -- Reply to this email directly or view it on GitHub: #55 (reply in thread) You are receiving this because you commented. Message ID: ***@***.***>

Good Morning Harald, The image, like most of the images used in the documentation, are SVG Files. https://github.com/GfSE/SAF-Specification/blob/TdSE2023/diagrams/SAF_Viewpoint-Grid-Structuring-Formalism.svg If needed, they can be downloaded and scaled without loss to any format you can print or display. -- Gruß, Alexander

[Harald-Vogel]

Yes, Alexander, thanks for this hint, it is known but the focus of my discussion "SAF-documentation improvements (proposals)" is improvements for working with this documentation as a SAF guide not problem solving. I did already what you proposed and this directed me to open this discussion. My proposals come from using this SAF documentation and make it more attractive for daily efficient work. This is my motivation to post some findings in this documentation.

[haarer]

Am 8. Dezember 2023 22:49:05 MEZ schrieb Christian Lalitsch-Schneider ***@***.***>:

Operational Capability Viewpoint: I need to able to express on one hand a composition and on the other hand an aggregation relations between different operational capabilities. We will have to add the option of an aggregation relationship. -- Reply to this email directly or view it on GitHub: #55 (reply in thread) You are receiving this because you commented. Message ID: ***@***.***>

Why? Just because UML has both Options, that doesnt mean we must use both. What is the difference in semantics, when a *Capability* is aggregated vs composed ? Capabilities are Not 'destroyed' Like instances within Software...

…

-- Gruß, Alexander

[Harald-Vogel]

I had this discussion with Markus Andres already. A composition relation usually generates parts automatically in a model and this makes the main difference and it makes sense in my opinion defining operational context and operational capabilities. Accepting both notations could be a solution if some capabilities are essential like "ESP" for a hybrid car (composition should be used) and other capabilities are not so important like "induction charging" (aggregation can be used). It tells me in this example what main capabilities are characterizing a car.

[haarer]

SysML knows part properties and reference properties - shown by black and white diamonds on BDD.

The intention of the SAF relationships OCYcomposedOF (and SCYcomposedOf) is to specify a whole part semantics( see https://github.com/GfSE/SAF-Specification/blob/main/developing-saf/concept/concepts.md#OCYcomposedOF )

IMO, that means we should change the example and possibly add a constraint text that composite association / part properties shall be used.

Capability Referencing
If a capabitity references an other, this is typically a "this needs that" relationship and we have that covered already by the dependingOn relations. (see https://github.com/GfSE/SAF-Specification/blob/main/developing-saf/concept/SAF_capability_F%20Definition.md and https://github.com/GfSE/SAF-Specification/blob/main/developing-saf/concept/SAF_capability_O%20Definition.md)

Capability Prioritizing
If the provision of a capability by a performer or system is of a certain priority, this should not be part of the capability structure, but be captured in relationship between capability and performer/system

IMO, using reference properties for this would be a very bad design choice.

Some Statements from SysML spec, ch 8.3.2.3:

• A property typed by a SysML Block that has composite aggregation is classified as a part property, ...
• A property typed by a Block that does not have composite aggregation is classified as a reference property.
• Part, reference, value, and constraint properties may be shown in block definition compartments with the labels 'parts,' 'references','values,' and 'constraints' respectively.
• On a block definition diagram, a part property is shown by a black diamond symbol on an association.
• A part property holds instances that belong to a larger whole.
• A particular application domain may establish its own interpretation of part-whole relationships across the
  blocks defined in a particular model, including the definition of operations that apply to the parts along with the
  whole. For software objects, a typical interpretation is that delete, copy, and move operations apply across all parts
  of a composite object.
• SysML also supports properties with shared aggregation, as shown by a white diamond symbol on an association.
  Like UML, SysML defines no specific semantics or constraints for properties with shared aggregation, but particular
  models or tools may interpret them in specific ways.

[odungern]

Usually, the difference between 'composition' and 'aggregation' is not about importance, but whether a part is essential for the nature of the whole (composition), such as a tree isn't a tree any more without its trunk, or whether it is optional (aggregation).