Compass component smart-link suggestions

[Keith Furnell]

When a Compass component's (ARI-based) URL is pasted in Confluence or Jira it is (by default) usefully rendered like this:

Switching to a card presentation additionally provides the component's description.

Here are some suggestions that would improve the value of integration with other Atlassian products through these smart-links:

1. Include Compass components in suggestions for the /link (Ctrl+K) macro (or provide a dedicated macro for inserting them)
2. Allow owner team, lifecycle stage, labels and/or scorecard status (and ideally selected custom fields) to be included in the card presentation
3. Allow Compass admins to choose a different field than Tier to be used as suffix
4. Render Compass/Jira/Confluence URLs in the Overview/Description of components themselves as smart-links

It doesn't seem to be documented but, when the URL of a Compass component's Announcements Page is pasted, it too offers card and in-line presentation, e.g.:

It would be useful to have similar functionality for other sub-pages (and ideally the ability to fully embed their content) e.g. API Specifications, Documentation & Dependencies.

Reference: https://support.atlassian.com/platform-experiences/docs/smart-links-from-jira-and-other-products/

[Andrei]

Hi @Keith Furnell

Thanks for reaching out.

Let me go through these one at a time:

Include Compass components in suggestions for the /link (Ctrl+K) macro (or provide a dedicated macro for inserting them)

We're actively looking into this, this is one workflow we're interested in bringing to Confluence as it tends to come up fairly frequently when we're doing design docs. ( i.e. typing out "component A talks to component B and that goes through component C owned by team W". Grabbing links for all of those is pretty painful 😃 )

Allow owner team, lifecycle stage, labels and/or scorecard status (and ideally selected custom fields) to be included in the card presentation

We don't have a ton of real estate to work with on the card view, but I'll raise this with our team and we'll see what we can land on. Can you tell me a bit more about the context you're using these card views in? What are the highest priority bits of information that you're looking to get to at a glance?

Allow Compass admins to choose a different field than Tier to be used as suffix

Can you say more here? What fields would you be interested in having in the inline view? Given the very limited real estate in the inline view, there are only a small subset that I could see not overwhelm the content, but I'm really interested in your use case here.

Render Compass/Jira/Confluence URLs in the Overview/Description of components themselves as smart-links

The description field on Components we're looking to keep as plain text and direct that more towards usage as a 'short description' that we can leverage in list views. The details field currently has full support for Atlassian Document Format, but to your point, doesn't support smartlinks. I'll at this to the backlog.

Thank you so much for all the suggestions, really appreciate you taking the time to write these down in such detail.

[Keith Furnell]

Thanks @Andrei for the prompt response. In answer to your questions:

Can you tell me a bit more about the context you're using these card views in? What are the highest priority bits of information that you're looking to get to at a glance?

TBH we haven't seen a heap of value in the Atlassian card presentation in general so far but, given the limited features for describing a component, we are faced with still needing a Confluence page for each Compass component. In this case I could see us wanting to place a Compass card at the top of the Confluence page, in order to convey basic information.

I wasn't aware of the size constraints (though I see now that longer descriptions get truncated), however basic information might include lifecycle stage, owner team or Jira project. Inclusion of labels or custom field values would be awesome, but I can see how the unrestricted width of these might be tricky.

Can you say more here? What fields would you be interested in having in the inline view?

I can see why tier was chosen however not all component architectures fall neatly into 4 tiers, in which case life-cycle stage might actually be more useful. For maximum versatility I think we'd like to be able to choose a (single_select) custom field, but I understand that this would mean non-deterministic value lengths.

The description field on Components we're looking to keep as plain text and direct that more towards usage as a 'short description' that we can leverage in list views

I see what you're saying but observe that this doesn't preclude rendering a text version of the "target" in list views. For instance it'd be great to be able to refer to another component (e.g. by slug) and have that render as a smart-link on the component overview, and as it's plain-text name elsewhere. That would avoid obvious problems when components get renamed.

The details field currently has full support for Atlassian Document Format, but to your point, doesn't support smartlinks

We won't be using this field until it's supported in config-as-code. Incidentally IMHO it would be better not folded by default, at least for short amounts of content.

Thank you so much for all the suggestions.

I thought of one more! Could the card presentation of a scorecard link present the distribution of Passing/Failing/Needs attention? That would allows us to build arbitrary dashboards in Confluence (unless that's something coming natively to Compass)?