🔌 Plugin: Glossary Plugin

[mufaddal7]

Summary

Software catalogs contain various information about a project. Teams often maintain a glossary which is an essential part of the catalog.

Can we build a Glossary plugin that can be used by backstage Entities

Plan

The glossary plugin will be an additional tab on the Entity Catalog page, which will be visible for the KINDs selected by the user. Terms and Definitions will be visible in a table format. The terms will be linked to the specific component via CompoundEntityRef (Entity ref triplet). Preferring to link terms to the catalog by this method as its the preferred method in backstage.

We will maintain the glossary in Backstage Database and use glossary-backend plugin to create the CRUD operations. The combination of Glossary Term and Entity Ref will be a unique identifier.

Logged in Users will enter details like this: 

Field	Example
Term	Service Catalog
Definition	A service catalog is an organized and curated collection of any and all business and information technology-related services that can be performed by, for, or within an enterprise.
Catalog	default:component/some-component-name

We will showcase a Global glossary, which will be reachable via sidebar navigation. Which will show all terms from different KINDs and Catalogs in the organization.

Secondly, there will be a Glossary tab inside the Entity Catalog page.

Prototype

[freben]

Why would this be keyed on entity ref? Aren't terms the same globally typically?

[Rugvip]

I'm curious what benefits this would have compared to a glossary page in the entity TechDocs? I could see the CRUD operations being a differentiation, but also quite a bit of work to implement fully?

[mufaddal7]

@freben Terms will be used globally, but linking them to refs can help them map to the respective software catalogs as well (especially mapping it with catalogs from KIND: Group and Domain). We can even make components in the EntityCatalog page for displaying terms associated with that respective catalog. Mapping it with entity ref also helps in distinguishing between terms with duplicate names. One term can have different meanings in different teams.

@Rugvip This can be a good value addition I believe, it will be robust to use and a new feature, which is very relevant with managing software catalogs. Also, a feature that will help developer adoption inside organisation. I am ready to work on this.

[Rugvip]

@mufaddal7 Yep a glossary is certainly very useful and we use it quite a bit internally, but it's generally just an additional TechDocs page. I'm wondering what value a separate plugin brings to the table?

Don't get me wrong btw, I don't think this is a bad idea, just pushing back a bit to make sure it's all well thought through.

[dweber019]

Just thought about a plugin like this, as we use a glossary internally too.

I totally agree that the glossary mostly is only a page(s). But adding a TechDocs page only solves one side. The engineers need to be constantly aware, that this site exists. We see a lot of re-definition of terms over documentations.

I would be nice if known terminology is auto highlighted in any TechDocs page, could be done as add-on and look like https://marketplace.atlassian.com/apps/1219677/smart-terms-for-confluence-glossary?tab=overview&hosting=cloud or https://marketplace.atlassian.com/apps/1211800/glossary-for-confluence?tab=overview&hosting=cloud.

To do this, I think a backend plugin would be necessary to maintain the glossary.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.