search

backstage / community-plugins

Community plugins for Backstage
Apache License 2.0
121 stars 96 forks source link

[Plugin] Glossary Plugin #235

Open mufaddal7 opened 1 year ago

mufaddal7 commented 1 year ago

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 ![image](https://user-images.githubusercontent.com/42934221/187152018-6ee1ddef-c03c-4c7f-810b-239c195e0010.png)
freben commented 1 year ago

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

Rugvip commented 1 year ago

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 commented 1 year ago

@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 commented 1 year ago

@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 commented 1 year ago

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.