Decide how to present domain documentation
- Dominant language
- No language data
- Stars
- 8
- Forks
- 2
- PR merge metrics
- No merged PRs in 30d
Description
### 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](https://github.com/slawr/vss-otaku/blob/master/frameworks/data-mesh/applying-data-mesh-principles-to-vss-vdm.md) I talk about how the [Principle of Data as a Product](https://github.com/slawr/vss-otaku/blob/master/frameworks/data-mesh/applying-data-mesh-principles-to-vss-vdm.md#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](https://github.com/slawr/vss-otaku/blob/master/frameworks/data-mesh/applying-data-mesh-principles-to-vss-vdm.md#seat-domain-1) as an example and could be a natural starting point.
2. In the same article I talk about the need for [federated governance](https://github.com/slawr/vss-otaku/blob/master/frameworks/data-mesh/applying-data-mesh-principles-to-vss-vdm.md#seat-domain-1) 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.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.