search

eclipse-arrowhead / documentation

Core specifications and black box documentation for Eclipse Arrowhead.
Eclipse Public License 2.0
3 stars 2 forks source link

ISO/IEC/IEEE 42010 conformance #1

Open sdhouib opened 2 years ago

sdhouib commented 2 years ago

The reference model (or Meta-Model, assuming that reference model and Meta-Model are synonyms in the document) of the Arrowhead framework should be conformant to the ISO/IEC/IEEE 42010 standard that defines architecture frameworks and specifies requirements on architecture frameworks: http://www.iso-architecture.org/ieee-1471/afs/

jerkerdelsing commented 2 years ago

Good comment @emanuelpalm will you have look into this .

emanuelpalm commented 2 years ago

After going through ISO 42010 briefly, it indeed seems to me as if the way I use the term "reference model" is largely equivalent to the ISO 42010 concept of "meta model". It also seems to me, however, as if there is no way for a "meta model" to claim conformance to ISO 42010 without being part of an architectural viewpoint. What I could do, however, is to make the terminology of the reference/meta model align better with ISO 42010 and rewrite the "Scope" subsection to describe how a document referring to the Arrowhead reference/meta model could claim conformance.

@sdhouib Can you confirm that my understanding is correct, or please explain how I am wrong?

@jerkerdelsing Is this something we want? This would likely take me some days of work, but I suspect we could get some quality gains through it that will spill over to other important Arrowhead documents, such as the documentation reference.

jerkerdelsing commented 2 years ago

@emanuelpalm if you and @sdhouib are in agreement please go ahead.

sdhouib commented 2 years ago

@emanuelpalm you're right. the Arrowhead meta-model is part of the architecture framework. This MM is used to create the Arrowhead model kinds (Examples of model kinds include data flow diagrams, class diagrams, Petri nets, and state transition models). My question is: what is the scope of the document? Are you planning to describe the Arrowhead Architectural Framework (stakeholders, viewpoints, model kinds, etc) or just the meta model that will support the creation of the Arrowhead model kinds ? We should maybe schedule a meeting to discuss.

sdhouib commented 2 years ago

maybe you should take a look to the Industrial Internet Reference Architecture (IIRA) document: https://www.iiconsortium.org/pdf/IIRA-v1.9.pdf

emanuelpalm commented 2 years ago

@sdhouib The idea is for the document to define concepts that are useful in the context of Arrowhead. Concepts such as "system", "system-of-systems", "interface" and so on. It is meant to serve as a dictionary of important Arrowhead words, not a guide to designing Arrowhead systems. In other words, it should answer the question "What is Arrowhead?", not "How do I design Arrowhead systems?".

An entire Arrowhead Architectural Framework is out of scope, for this document at least. If we ever come to writing such, we would likely split it into multiple documents, just as the IIRA is. The reference/meta model would then likely be part of that larger framework. My on-going ambition is to produce the bare minimum of documentation required to make the current engineering challenges of Arrowhead easier to address. Challenges such as how to document Arrowhead systems from an engineering perspective, what information to store about a service in the service registry, and so on.

emanuelpalm commented 2 years ago

One concern I have with ISO/IEC/IEEE 42010 is that it is quite complex and introduces vocabulary I believe to be foreign to most. Viewpoints, views, model kinds, and so on. A risk of adhering to it too strictly may be to make our documents too hard for enough people to endure reading to the point of understanding.

sdhouib commented 2 years ago

@jerkerdelsing we should consider the ISO/IEC/IEEE 42010 in our work on the MM and UML profile. All the technical framework that is compliant to IEEE 42010 is available in Papyrus. An example of an architectural framework that we specified and then implemented in Papyrus is this one: https://www.mdpi.com/sensors/sensors-21-05136/article_deploy/html/images/sensors-21-05136-g001.png

emanuelpalm commented 2 years ago

@jerkerdelsing @sdhouib How about me doing the following:

  1. Renaming the document to "Eclipse Arrowhead Meta Model: Core Concepts".
  2. Making sure there is better terminological alignment between ISO 42010 and the document (names of stakeholder roles, etc.).
  3. Rewriting Section 1.2 "Scope". The phrase "reference model" is removed with the current figure. The scope of the document as a form of dictionary is stated without assuming the reader is familiar with ISO 42010. The rewrited section ends with a mention of how ISO 42010 compliance is covered in Section 4.
  4. Updating Section 1.3.1 "Diagrams" such that it is more explicit about how "is", "has" and other key relationships used throughout the document are to be interpreted.
  5. Rewriting Section 4 "Conformance Requirements". The section is written with Section B.2.6 of Annex B of ISO 42010 in mind. By that I mean that the conformance requirements are made sure to contribute to fulfilling ISO 42010 requirements. A subsection is also added to Section 4 that describes how the document can be part of an ISO 42010 architectural viewpoint.

The point of these changes would be to make ISO 42010 conformance a possibility for those who know what it is and could benefit from it, while also making sure that understanding or being concerned with ISO 42010 never becomes a strict requirement to be able to understand and take advantage of the document.

emanuelpalm commented 2 years ago

I would, of course, also have to update Section 1.4 "Relationships to Other Documents" such that ISO 42010 is brought up there.

sdhouib commented 2 years ago

Sounds good! thanks. I will go through the MM diagrams and give you my feedback

emanuelpalm commented 2 years ago

@sdhouib Thank you! I hope you can review the changes listed above when I have completed them.

emanuelpalm commented 2 years ago

@sdhouib I've now made all the changes I listed. You can view a copy of the update document by clicking the link below.

I've update quite a lot more than I thought I would initially, as I found various problems throughout the document while I went through it. Even though I would love to have you look carefully at all parts of the document, I would be especially pleased if you could look carefully at Sections 1 and 4. If you believe anything should be added to section 4 regarding ISO/IEC/IEEE 42010 conformance, please let me know. If you have anything more substantial to contribute, we may add you as a coauthor of the document.

Eclipse Arrowhead Concepts Reference v1.0.pdf

emanuelpalm commented 2 years ago

By the way, the document is now called "Eclipse Arrowhead Concepts Reference" instead of "Eclipse Arrowhead Meta Model: Core Concepts". The former seemed more clear to me, even though the latter perhaps is more precise.

sdhouib commented 2 years ago

thank you @emanuelpalm for the new version! I will review it next week.

emanuelpalm commented 2 years ago

I just updated the document again. Please commence with your review whenever you have time. For your convenience, here is a link to the document PDF: https://github.com/eclipse-arrowhead/documentation/raw/master/distribution/Eclipse%20Arrowhead%20Concepts%20Reference%20v1.0.Proposal.pdf