Documentation overview

[MatsBJohansson]

Need for an overview of what documentation we need for Eclipse Arrowhead, identify what the gaps are and define needed actions.
A Roadmap subgroup are to be established.

[Documentation strategy - v08.pptx](https://github.com/eclipse-arrowhead/roadmap/files/7433737/Documentation.strategy.-.v08.pptx
Arrowhead Documentation overview - v04.xlsx
)

[emanuelpalm]

Looking at your GitHub profile, I assume you are new here. Welcome! If you need any help with uploading material or have other questions, please don't hesitate to contact me. I assigned myself to the issue to indicate that I will help you here. I don't want to put my e-mail here out in the open, but you should be able to get it through @jerkerdelsing or someone else you know in the Arrowhead project. If you question is of general interest you can simply write it here.

[MatsBJohansson]

Following actions from the meeting with the Roadmap subgroup for “Documentation overview/strategy” on November 10th, please review attached excel file and respond to me ([email protected]), or as comment to this Roadmap issue, by Monday December 6th .

1. In the tab “Actors in process phases”, please review the list of actors (Column A: “Actor (Producer and/or Audience) category”) and propose updates. I.e. which kind of actors would benefit from any kind of documentation regarding Eclipse Arrowhead?
2. In the tab “Documentation overview”, please review the list of document Items (Column B: “Doc item label”) and propose updates. I.e. which kind of documentation regarding Eclipse Arrowhead do we have and/or do we need?

Kind regards
Mats

Arrowhead Documentation overview - v05.xlsx
Documentation strategy - v09.pptx

[emanuelpalm]

ISO/IEC/IEEE 42010, which standardizes the formulation of software-architectural documentations, models and languages, contains the following list of general actors. I've added my own interpretation after each actor name.

􏰀1. User. A stakeholder taking, or trying to take, advantage of the end utility of a certain entity.
2.􏰀 Operator. A stakeholder operating a certain entity with the end goal of it producing a certain end utility for users.
3. Acquirer. A stakeholder in the process of acquiring, or considering to acquire, an Arrowhead system with the intent to operate and/or use it.
4. Owner. A stakeholder that owns an Arrowhead system.
5. Supplier. A stakeholder in the process of supplying, or considering to supply, an Arrowhead system to an acquirer.
6. Developer. A stakeholder involved in the development of the hardware and/or software components that make up physical devices hosting Arrowhead systems and/or the Arrowhead systems themselves.
7. Builder. A stakeholder involved in the installation of the devices and systems making up an Arrowhead automation system.
8. Maintainer. A stakeholder involved in maintaining the physical devices that host Arrowhead systems, as well as the Arrowhead systems themselves. Maintenance primarily involves repairs and software updates.

To that list I would also like to add (9) Researcher and (10) Architect. The former is a stakeholder involved in the analysis or development of significant entities, particularly with the ambition of facilitating attributes or use cases that cannot be realized without refining, extending or replacing those entities. The latter is someone who seeks to improve upon or extend the Arrowhead framework itself, by, for example, writing core documentation or producing architectural descriptions.

[MatsBJohansson]

Arrowhead Documentation overview - v06.xlsx

[MatsBJohansson]

Arrowhead Documentation overview - v07.xlsx

[PerOlofsson-Sinetiq]

I would like to rise the question of expanding the Design documentation into separate lines in the matrix. I think that in particular the abstract documents like SD, SysD and SoSD would be of use in requirement/design stages of the development while the concrete documents like IDD, SysDD and SoSDD will be created somewhat later in the process. The concrete documents also would benefit from some kind of feedback loop after deployment/comissioning.

[MatsBJohansson]

Updates and notes at meeting 2022-04-01
Arrowhead Documentation overview - v09 w notes 220401.xlsx

[emanuelpalm]

@PerOlofsson-Sinetiq This has been discussed also in:

• "Description" vs. "Design Description" #34

Look especially at #34 (comment).