Improving your Domains with automated Popularity, Quality and Maintenance scores
Jargon is both a platform to develop Domain Driven Designed APIs and Data Models, as well as a repository of reusable Domains. When searching for a Domain to Import, Jargon ranks the results based on the Domain’s scores for Popularity, Quality and Maintenance (or P, Q and M respectively)— allowing better Domains and ones that are reused more to bubble to the top to be reused again.
Let’s take a look at what these scores mean, how Jargon calculates them and some tips you can use to improve the quality of your Domains.
Combined Score
Each Domain is assigned an overall score that is used to boost its ranking in the search results. This score is a result of applying weighting to the individual scores of:
- Popularity × 0.4
- Quality × 0.35
- Maintenance × 0.25
Looking at those weights, you’ll see that Popularity contributes the most to a Domain’s overall ranking — this is deliberate. One of our missions at Jargon is to improve data interoperability — a measure of how many people can share and reuse data from others without manual intervention. A key enabler for this outcome is reuse — so Jargon adds more weight to the Popularity score of a Domain, helping to group people around already designed and reused Domains.
You can see the scores for a Domain in lots of different places around Jargon — essentially anywhere there is a list of Domains (like in search results, the Import process, or in a Team’s profile page), and anytime you’re looking at the Domain’s detail page. The scores are displayed as a bar chart, with individual bars for P, Q and M. If you click the chart, you’ll be taken to the detailed analysis page.
Here’s an example of what the P Q M chart looks like, up in the top-right corner:
Popularity
There’s only a single criteria measured to calculate the Popularity score: Uses. Uses is a measure of the number of times a Released Domain has been Imported into a Domain that has itself been Released. Only Imports in Released Domains contribute to the score as it’s a more accurate indication of interoperability and reuse.
Quality
Quality measures the ‘goodness’ of a Domain and indicates how much effort has gone into designing and documenting it. There are 5 criteria that contribute to the Quality score:
- Domain Artefacts × 0.2 — Measures how many artefacts (like a Readme) the Domain has
- Business Identity × 0.05 — Measures how many Classes have a unique identifier
- Business Definitions × 0.6 — Measures how many of your Classes and Properties have definitions to explain their intent
- Domain Description × 0.05 — Measures that the Domain has a short (but not too short!) description to help consumers understand what it is for
- Domain Snapshots × 0.1 — Measures how many Snapshots have been taken in the last 1, 6, 12 & 24 months
For each of the measures, Jargon will give you a detailed description and explanation of how the score is calculated, and the data for the Domain that was used in the calculation. It looks a little like this:
In this example, we can see how Jargon weights each of the time periods where Snapshots were taken, and how they contribute to the score for this weighting. Jargon also shows you the raw numbers that were used to calculate the score.
Maintenance
Maintenance is a score of the hygiene of the Domain, indicating how well it’s taken care of.
There are only two measures for Maintenance:
- Open Issues × 0.4 — Measures how many Issues have been resolved vs. those that remain open
- Domain Releases × 0.6 — Measures how many Releases have been taken in the last 1, 6, 12 & 24 months
Tips to improve the scores for your Domains
Ok, so now that we know a little more about how Jargon calculates scores for your Domains and we know how to examine the detailed results, we can take a look at which areas to target to improve your Domain rankings.
Note: This isn’t meant to be a popularity contest. Improving the ranking of your Domains shouldn’t be what you’re aiming for — instead you should be trying to make your Domains as good as possible so that it makes them more appealing to others, eventually improving interoperability.
Here are the three best things you can do to improve your Domains:
1 — Add good Business Definitions to every Class and Property
Having Business Definitions for everything in your Domain is an easy way to get the full 0.6 component of the Quality score. In practice, this means that if you have Business Definitions for every item in your Domain, you can increase your overall score by around 20% — and that’s quite a big improvement. The impact that good (or bad!) definitions of your Domain can have on the score is intentional. You can have the best designed and maintained Domain in the world, but it won’t help interoperability if there is confusion and ambiguity around what it means and how you’re meant to use it.
2 — Make Releases (but only when they add value)
Creating regular releases makes it possible for others to reuse the work you’ve done. This isn’t only important because it saves people time; although that’s part of it. The main reason is because duplication of similar Domains hurts interoperability. Having multiple Domains that all nominally do the same thing, but aren’t identical, means systems that use them aren’t able to easily exchange data.
3 — Document your Domain with Artefacts
Having Artefacts (Readme, State Lifecycles, etc) adds another dimension to explaining your Domains and making them easier for others to understand. A good Readme is more than just a collection of information about the Domain, it adds a detailed explanation of the business problem it aims to solve and generally includes links to other online information to round out the picture. Similarly, State Lifecycles and API specifications help explain a Domain’s dynamic behaviour.
Wrapping up:
So that’s a an overview of how Jargon scores your Domains, why it scores it the way it does, and some things you can do to improve them.
If you have any further questions about improving your Domains, you can:
- check the Getting Started Guide
- leave a comment below
- raise an issue at the jargon issue tracker GitHub repository
- Sign up for a free Jargon account and try some out for yourself
