Arrowhead documentation strategy need to be documented

[henrikbylund]

Some comments from me, a newcomer to the Arrowhead community, based on reviewing the GSoSD. They are not comments on the specific document in itself, but rather on the documentation structure.

So, from the perspective of a user of Arrowhead - a service developer/integrator so to speak:
My main interest in documentation would be, in no particular order:

• What does the platform offer - the capabilities
• How do I actually integrate systems using this platform - example use cases
• What are the core concepts of SOA?
• How are these core concepts adressed by the Arrowhead architecture?

These are not neccessarily the same document:

• An introduction to SOA and its core concepts, and how they map to Arrowhead concepts (like the introduction in the GSoSD document) could very well be an easily accessible web page somewhere. A "one-pager", not a dry PDF document. Youtube videos serve this purpose well too.
• The capabilities are probably expressed best in traditional viewpoints - a capability map, API documentation etc (the SD and IDD document concept fits in here, except they are fairly standalone and in the current incarnation not using proper media. A programmer in 2023 doesn't refer to word documents for API documentation). When describing the capabilities, systems are completely irrelevant in my opinion. The Core Arrowhead is a black box with externally observable capabilities expressed as services. How they are realized as systems are not of interest, unless I want to look at implementation-specific attributes such as realiability metrics or licensing details. But then I should refer to a specific Arrowhead Core implementation's documentation.
• Use cases and how to implement them are also a lot more accessible as web pages with code snippets using syntax highlighting, hyperlinks etc.

What am I leaving out above? Many of the actual definitions of Arrowhead - the normative statements so to speak. The service definitions above is one example - on an Arrowhead platform I would expect the identity management capability to be well defined and governed by IDDs that implementations declare conformance to. But there are other potential architectural principles as well that need to be documented, such as term definitions (which is a separate document already), security considerations etc.

Then there are documentation needs that may be more controversial - I don't see a point in defining "Core Systems" for example, that's up to whoever implements the core services. There might be a single system implementing all the core services for example. Probably a bad way of implementing it, but it should be valid as long as the services are implemented to spec. I think this is an important part of SOA, to hide implementation details, and be in a mindset of making as few assumptions as possible about services I integrate with.

Many of these points don't really adress the concerns of a user of an Arrowhead platform, but are important to govern by the community to ensure a healthy architecture with healthy implementation competition by standardising the right things.

So already there are (I claim!) two separate stakeholders with separate concerns. I think a problem with the GSoSD Core Systems document is that it tries to adress many of these concerns at the same time. It mixes normative definitions with non-normative examples without it being clear what is what.

Maybe it would be useful to create a documentation strategy by defining some basic stakeholders, concerns and viewpoints? (Refering to terms in the ISO 42010 conceptual model for those familiar with that - even if that is more focused on dry architectural descriptions :) )

[emanuelpalm]

My impression from the past few Roadmap WG meetings is that something like the ISO 42010 stakeholders, concerns and viewpoints, among other things, needs to be documented in officially approved documents as a means of us agreeing on what Arrowhead is within the project.

Since ISO 42010 is a thing, why not use it as a starting point?

[jerkerdelsing]

To me it's very much a question of documenting the strategy. There exist a couple of slide decks capturing the current approach. @henrikbylund is this something you can take on and create Documentation strategy document (please use the Latex template, [https://github.com/eclipse-arrowhead/roadmap/tree/main/Documentation_templates/LaTeX])

[henrikbylund]

@jerkerdelsing - I would be happy to create a draft, I'll get back to you with a time plan. Do you have a link to the slide decks you mentioned?

[jerkerdelsing]

@henrikbylund https://github.com/eclipse-arrowhead/roadmap/blob/main/Governanace_strategy/Eclipse_Arrowhead_Roadmap_organisation.pptx