How do we make better use of our CDM Resources?

[chrisisla]

Introduction

When a user wants to get started with the CDM there are three main places they will be directed to:

• The main FINOS website
• The new CDM microsite (still WIP but live at cdm.finos.org)
• The CDM github page

At these three locations we probably have virtually all the information that people could want. However, it is not that easy to find what you need.

In this Discussion I want to see if we can decide a path to improve how the CDM resources are presented to the world.

I have focused on the new cdm.finos.org microsite and the github page, as these are probably the most visited sites. For each location I have suggested the sort of questions that we need to answer. I’ve tried to consider the sort of things that new/existing contributors, modellers or developers would need, as well as information that people looking to assess the CDM for use at their organisations might require. Processes and best practices for CDM maintainers are also proposed.

Note

This is quite a long post so apologies in advance!
Please take the time to read through and post a comment with your feedback. It will be most appreciated 👍

CDM microsite (cdm.finos.org)

This is the main entry point to the CDM documentation rather than the model/code. As such, we need to make sure the more business/administration focused documentation is available here. We can then provide links to this documentation on github if we need to.

Note: The microsite has a direct link to both the CDM documentation and github. Adding a reciprocal link from github back to the microsite is recommended.

I have split the required details into headings.

Version information

• Where they can see and edit the model
• What version of the model they should be looking at
• What version of the CDM they should use
• Where to get that version of the CDM
• What the release strategy is for the model
• What is included in the previous/current/future releases of the model
• What coverage there is in the model for their specific business requirements

Contribution information

• How they can suggest a change to the model
• How they can contribute a change to the model
• Point to github for the rest of the technical details
• Where to request feedback on potential changes they are considering making to the model
• How long they should expect to wait for a change to be reviewed/promoted/rejected
• What is the appeal process if a PR is rejected

We also need to provide documentation that will assist maintainers in their roles. This must provide:

• Clarity on what their role entails and what responsibilities they have and to who
• To know how to triage a new PR
• To know what labels are available to add to PRs
• Clear guidance on how to determine which labels to add to a PR
• To know if they are expected to run/attend any working groups and their cadence
• Documentation explaining how they are to use github e.g. linking Issues to PRs

The majority of this information is either available in the CDM documentation or on github (somewhere). The main task I think we need to undertake is to make this information more obvious on the new site.

The headings could be links on the main landing page for example. Alternatively, the headings and details could be provided as a new FAQ. Suggestions welcome!

CDM github (github/finos/common-domain-model)

The github repository is focused on engaging the modellers and developers in the community. The detail here should be more tailored to their requirements, but links back to the microsite would also be valuable.

If possible, the main github page should have links to the following information. Again, I have tried to split this into headings based upon content.

Model/CDM Administration/Governance

• Who the maintainers are and how to contact them
• How to request a meeting to present some work
• When and how to request an ad-hoc meeting to review a contribution
• What the expectations are when making a contribution i.e. the process they have to follow
• What responsibilities they have if the contribution fails/does not compile
• The design principles that a contribution should adhere to
• Details on maturity and diversity of the community supporting the model

Github/Issue & PR Administration

• How to use github to create an Issue
• How to use github to create a Pull Request
• Linking Issues to Pull Requests

CDM Technical details

• How to install the CDM for various programming languages
• How to get started with the model in various programming languages
• Where to find code examples in various programming languages
• How to create a code generator should they need one

Once again we do have a lot of documentation in github already that will help with this. The main artifacts I found when looking through the content were as follows:

• Process for getting a PR into production – on CDM - Development Operating Model - PR Labels and processing  #2129
• Documentation on how to get started with github – on Resources for pre-requisite technical skills required to start working on the CDM #2182
• Explanation of labels and their relevance – on CDM - Development Operating Model - PR Labels and processing  #2129
• Contribution Workflow – on March 14th - Common Domain Model Inaugural Meeting Minutes #2011

These are some additional details associated to our usage of github that need to be documented somewhere (for example, how to link Issues and Pull Requests). These could be documented on github or the microsite – wherever they are hosted it would be beneficial to have them linked to in github itself.

Additional questions
Whilst going through the pages and the processes a few questions came up:

• There needs to be more clarity on what “2TA Maintainer” approval and review actually means:
  • If a TA makes a proposal and approves it do they count as one of the 2 TAs?
  • Is the actual drive of this 2TA approval attempting to say that all 3 TAs need to approve this type of PR?
  • Does it really need to be maintainers from a TA or can one of the other community maintainers approve this type of PR?
• CDM Readme
  • The details on the github main page do not seem to actually reflect the details of the project. For example, there is a section about Working Groups that then describes the Steering Working Group (incorrectly I think). I don’t think this is correct anymore and should be updated.
• Labels on github
  • Do we really need to add labels on Issues as well?
  • Can we change the permissions so that contributors can add the labels or does this need to be controlled by the maintainers?

[chrisisla]

@dshoneisda @iansloyan @brianlynn2 @ADaleISLA @gabriel-ICMA @tomhealey-icma @lolabeis @minesh-s-patel @dschwartznyc

Please let me have your feedback on the above, any comments on any of the suggestions will be gratefully received!

[lolabeis]

Agree with the drive to better orient first-time comers and consolidate where the information is located - which would also serve long-time comers!

As you point-out, for the most part the required information exists, it's just that it's scattered around, e.g. in a GitHub issue discussion. There is also a lot of content in the CDM documentation, now available in the micro-site and which historically contained everything (e.g. governance, how to contribute, version management etc.). Some of this could be extracted and positioned more prominently, so that the CDM documentation is kept "pure", i.e just answering what the model is / does. As a result of this fragmentation, some of the content is duplicated and partly out-of-date as you rightly noticed.

Another suggestion is to make the immediate landing content more engaging. Ideally someone's first contact with the CDM would be a series of videos on how to get started. @minesh-s-patel recently experimented with some AI tool that produced decently narrated videos based on some screen recording and a written script.

[chrisisla]

No further comments received since September last year so closing this discussion.