Decide how to present domain documentation

[slawr]

Problem Description

Whilst GraphQL SDL is intended to be self documenting we can see that in automotive that some VDM domains will require supporting explanation. An example would be the great work the Capabilities project has done to document the properties of the Seat domain.

We should agree broadly how to publish such information for the domains maintained by COVESA. Whilst the content would come from the subject matter experts creating the domain types, there is a cross-domain/federated governance presentation aspect that it would be helpful to the VDM whole if there was some presentation consistency across the domains. For example, they use the same online documentation site.

Ideas

Domain documentation would be an iterative process over time, but here are some ideas to seed discussion.

Approach

1. In my article on using the four principals of data mesh I talk about how the Principle of Data as a Product uses product thinking to create products with great usability. Considering how domain documentation supports usability could be one task in improving the VDM data model product. The article uses the work on the seat domain as an example and could be a natural starting point.
2. In the same article I talk about the need for federated governance to balance agility in domain development against maintaining interoperability and usability across the domains. The presentation aspects of the documentation could be considered as a task in governance development and the seat example used as a means to develop it.

Implementation

1. It would make sense for such documentation to stay close to VDM itself. This could be markdown files in VDM domain trees, but sections in an online doc site, like the one deployed for S2DM, would be more flexible.

[slawr]

I would be happy to contribute to this development