External component description content

[Keith Furnell]

The "Description" field of the Overview page provides both a plain-text field and (since this recent change) a fuller rich-text "More details" field (which are kind of analogous to the "summary" and "description" fields respectively of OpenAPI).

Often the descriptive content that might be used to populated these fields will already exist elsewhere. Is there any intention for the Overview page to eventually allow displayed content to be sourced from:

• wiki files (i.e. README.md) committed to the linked repository
• a Confluence excerpt macro
• a "starred" link from the Documentation page

Any of these would seem preferable to duplicating such content in a Compass-specific place.

[Oleksii Melnyk]

Hi @Keith Furnell !

Right now, Compass doesn’t natively support pulling the Overview description directly from an external source like a repository README, a Confluence excerpt, or a starred Documentation link. At the moment, the content has to be managed directly within Compass.

For now, a couple of practical approaches I’ve seen:

• Keep the Compass “Description” short (almost like a summary) and link out to the README or Confluence page for the full details.

• If you want automation, it’s possible to push content into Compass using the Compass API, so some teams sync their README.md into the overview field programmatically.

[Keith Furnell]

Thanks for the suggestions @Oleksii Melnyk. The first approach would have more potential if component Descriptions supported hyper-links 😊

I will keep the overall question (of whether there is any intention to provide support for richer component descriptions) open for now.

Maintaining this content outside of Compass (even if synced via API automation) seems to negate the potential for Compass to be the source of truth for component data.