"Description" vs. "Design Description"

[emanuelpalm]

@jerkerdelsing @palvarga @tsvetlin As part of my current work of producing a reference model for Arrowhead, I'm writing a glossary of key Arrowhead terminology.

In that glossary, I'm trying to define the words "description" and "design description" such that it becomes clear how, for example, a System Description (SysD) is different from a System Design Description (SysDD).

These are the definitions I currently have of "description" and "design":

Description
Facts about an entity or class of entities, expressed in the form of a model, a text, or both.

Design
Every document, model and other record describing how a certain artifact can be implemented or realized.

None of the definitions should be very surprising. What is baffling me abit, however, is how to define "design description". Looking at the definition of "design", you can clearly tell that a design is a form of description. In other words, a design description is a "description of a description". To me, that makes it sound as if a design description is a form metadata or summary. Given that understanding, it sounds as if a SysDD should be a less exhaustive document than a SysD, which is the opposite of what is the case.

As far as I can tell, a possible solution could be to rename the SysD document to something like SysID (System Interface Description) or SysOD (System Operation Description). Perhaps I've been staring too much at these words by now, but to me, interface and design seem to contrast each other well. Sure, an interface must also be designed, but the difference between a system interface and a system design should be quite clear (the former only describes a part of the latter).

If we follow through on this name change, it suggest we rename the IDD (Interface Design Description) to SID (Service Interface Description) and the SD to ASD (Abstract Service Description). I argue that it would provide better coherence among the document names than we have today.

Any other suggestions?

[palvarga]

Hi @emanuelpalm and All,
This could be a burning issue IMHO. The SD, SysD, SysDD documents are not filled by the system/service creators for some reason, any could this be that this issue lays behind? If so, I think we must act fast. (Although, I doubt that this is the reason.)
This concept of documentation split and naming convention comes up in different shapes and forms. As well as the actual format of the documents. IMHO we could rename the documents in any ways, certainly.

The paper that describes the originally proposed structure is from 2014 - https://www.researchgate.net/publication/269220878_The_Arrowhead_Approach_for_SOA_Application_Development_and_Documentation and I have no problems with changing it completely - form, naming, anything. My only concern is that ... whatever we should suggest must support the SOA approach (vendor-independent parts), it must allow looking under the hood (white box description), and clear definition of the "interfaces" (people working at different domains understand different things as "interface").

Without thinking the whole thing through and providing a solution that serves the purpose of independent groups could work together and use, integrate each others' things because they understand both the "logic" and the "interface", it would be just an academic discussion. The orifóginal suggestion was actually made through listening to industrial players at different fields, and trying to fit together with their jigsaw puzzle.

My short answer is already there I think: we can rename anything. The effect in the current case is questionable, without further actions, and I am not that naiive that this change would start a quiet revolution and people would start writing SIDs and ASDs.
The direction could be good, Emanuel - think bigger! :) (honestly!)

[emanuelpalm]

@palvarga Just as you say, I don't think the naming is a major reason why these documents are not being written. I believe that has more to do with lack of explanations and examples, which is something I will address with the documentation reference I will start writing later this year. Better names only help us get new people understand faster (as well as helping me motivate why things are the way they are in the reference model ;-) ). I don't think the actual setup of documents need to change. My only concern is communicating their purposes with as much clarity as possible to people completely new to Arrowhead.

What I find confusing is how the SD and SysD have similar names (which should indicate that they are related), but the SysD refers to the IDD, which does not have a similar name. The IDD name corresponds with the SysDD and SoSDD, neither of which refer to the IDD. Once I learned that the SD is an abstract description of a service, I started to wonder why there wouldn't be an abstract description of the system, or system-of-systems. In my mind, it seems as if the following "should" be the document structure:

I can discern three columns of abstraction (in addition to the three rows of magnitude), going from (1) totally abstract to (2) concrete interface to (3) concrete everything (the CP and SP belong to column 2). I understand that the value of abstract system descriptions and system-of-system descriptions may be negligible in many contexts. They would not be completely superficial, however. For example, a company may want to maintain multiple variants of the same system (like a pump), designed for different conditions (different fluid viscosities, temperatures, etc). The pump is going to function in a similar manner every time, but details about how to interface with it is going to change (one variant may have a valve that other variants lack, etc). That would make it convenient to have one over-arching document giving the big picture (ASysD), while having all variants (SySIDs) refer to that big picture.

What I don't like about my diagram is that the number of document types is becoming a bit unwieldy. I do think I would prefer the ASoSD and ASysD documents not existing as formal document types. If anyone would need something like that, I guess nothing stops that person from simply writing a separate document and referring to it.

@palvarga What kind of "thinking bigger" do you have in mind? :-)

[jerkerdelsing]

I do not see it meaningful to change names and content of a lot of things and documentation in this action.
What I do find meaningful is that we have it all explained and gathered at one place, the SoSDD of Eclipse Arrowhead.

[emanuelpalm]

@jerkerdelsing @palvarga I guess that is the end of the name-chaning discussion then?

I could perhaps amend my definitions as follows:

Description
Facts about an entity or class of entities, expressed in the form of a model, a text, or both.

Note 1: When used with certain other words, the term takes more specific meaning. For example, a system description is a description of the purpose and interfaces of a particular system implementation. Another example is service description, which is a description of the purpose and abstract functions of a particular kind of service.

Design
Every document, model and other record describing how a certain artifact can be implemented or realized.

Design Description
A description of the design, or implementation, of an artifact.

[emanuelpalm]

After a discussion with @jerkerdelsing, it was decided that this is not something that will be addressed directly. The current names will remain and the terms "description" and "design description" will receive no clarifications beyond their definitions, if included at all in the reference model.

Since there is nothing more to discuss, I'm closing this issue now. Thank you @jerkerdelsing @palvarga @tsvetlin for showing interest in my question.