Document the fact that entity fragments exists

content/docs/details/decorating-components/index.md

@@ -0,0 +1,44 @@
+---
+title: Introduction
+publishedDate: '2023-09-05'
+description: An introduction about decorating components.
+---
+
+Catalog is built around the concept of [entity descriptor YAML files](https://backstage.io/docs/features/software-catalog/descriptor-format/), therefore, any change you wish to make to your components, needs to be done via editing those files. 
+
+However, as YAML files can grow in complexity, they can become challenging to read and maintain. Editing those files, can sometimes be a long process, especially if ownership is shared accross the teams in your organization.
+
+Idea behind component decorator is to provide an easy way to enhance readability and usability for different components used accross organization. Furthermore, this enables decorating components which are automatically ingested catalog data/components from an existing external API.
+
+## Decorating components
+
+In order to access the decorator page, navigate to component page and select 'Decorate entity' from kebab menu at top right corner:
+
+![Decorate component](./decorate_entity.png)
+
+This will navigate you to the page where you can decorate your component with links and annotations, without a need to manually edit YAML files in your version control system. All of this is done via UI, in specifically designated sections.
+
+
+A visual representation of the YAML structure of the component, is shown in Existing Entity section of the page.
+
+![Existing component](./existing_entity.png)
+
+
+Adding links is done via 'Add link' button in 'Links' section. 
+
+![Add link](./add_link.png)
+
+New link properties need to follow [link properties types](https://backstage.io/docs/features/software-catalog/descriptor-format#links-optional). Usually semantics of the type field are undefined, but we have added few predefined options you can select from a dropdown list.
+
+Adding annotations is done via 'Add annotation' button in 'Annotations' section.
+
+![Add annotation](./add_annotation.png)
+
+New annotation properties need to follow [annotation properties types](https://backstage.io/docs/features/software-catalog/descriptor-format#annotations-optional). 
+You will find all existing annotations used in components accross catalog in a dropdown list.
+
+When you are happy with added annotations or/and links simply click 'Save' button and you will shortly see you changes.
+
+![Save changes](./save_decorator.png)
+
+<b> Please note, all of the changes are kept and displayed in your Backstage instance, but YAML files in version control system remain intact. </b>

content/docs/docs-nav.yaml

@@ -78,6 +78,7 @@ nav:
       - The catalog:
           - Managing locations: '/docs/details/location-management/'
           - Modelling dependencies: '/docs/details/showing-dependencies/'
+          - Decorating components: '/docs/details/decorating-components/'
           - Removing components: '/docs/details/unregister-components/'
           - Previewing component changes: '/docs/details/previewing-changes/'
           - Troubleshooting the catalog: '/docs/details/troubleshooting-the-catalog/'
@@ -137,4 +138,4 @@ nav:
           - Track Sonarcloud Project Issues/Hotspots: '/docs/tech-insights/track-sonarcloud/'
           - Track On-prem Sonarqube metrics: '/docs/tech-insights/track-sonarqube/'
           - Enforce branch protection: '/docs/tech-insights/enforce-branch-protection/'
-          - Track CODEOWNERS adoption: '/docs/tech-insights/track-codeowners-usage/'
+          - Track CODEOWNERS adoption: '/docs/tech-insights/track-codeowners-usage/'

yarn.lock

@@ -5013,11 +5013,6 @@ deep-is@^0.1.3:
   resolved "https://registry.yarnpkg.com/deep-is/-/deep-is-0.1.4.tgz#a6f2dce612fadd2ef1f519b73551f17e85199831"
   integrity sha512-oIPzksmTg4/MriiaYGO+okXDT7ztn/w3Eptv/+gSIdMdKsJo0u4CfYNFJPy+4SKMuCqGw2wxnA+URMg3t8a/bQ==
 
-deepmerge@^4.0, deepmerge@^4.2.2:
-  version "4.2.2"
-  resolved "https://registry.yarnpkg.com/deepmerge/-/deepmerge-4.2.2.tgz#44d2ea3679b8f4d4ffba33f03d865fc1e7bf4955"
-  integrity sha512-FJ3UgI4gIl+PHZm53knsuSFpE+nESMr7M4v9QcgB7S63Kj/6WqMiFQJpBBYz1Pt+66bZpP3Q7Lye0Oo9MPKEdg==
-
 defer-to-connect@^1.0.1:
   version "1.1.3"
   resolved "https://registry.yarnpkg.com/defer-to-connect/-/defer-to-connect-1.1.3.tgz#331ae050c08dcf789f8c83a7b81f0ed94f4ac591"