fix: corrected resource annotations page (#62)

content/en/docs/annotations/_index.md

@@ -1,14 +1,14 @@
 ---
-title: "Annotations"
-linkTitle: "Annotations"
+title: "Resource Annotations"
+linkTitle: "Resource Annotations"
 weight: 5
 description: >
-  This section covers annotations, which are used to provide additional metadata for resources.
+  This section covers resource annotations, which are used to provide additional metadata for resources.
 ---
 
-One of the key features of Score is the ability to attach additional metadata to your resources using Annotations.
+Some Score implementations require more information about a specific resource in order to provision it. Resource Annotations provide a standard way of providing implementation specific information about a resource.
 
-## How to use annotations
+## How to use Resource Annotations
 
 Use annotations to provide additional metadata for resources. Annotations are defined as a map with keys and values that provide additional information to a resource description.
 
@@ -24,17 +24,17 @@ resources:
 
 The resource `your-resource` has a single annotation with the key `your-annotation-key` and the value `your-annotation-value`.
 
-## Why use Annotations?
+## Why use Resource Annotations?
 
-There are several reasons why you might want to use Annotations in your Score files:
+There are several reasons why you might want to use Resource Annotations in your Score files:
 
 - **Informational hints**: Annotations are used to provide additional information to anyone or anything interacting with your resources, defined in your Score file. This could be helpful instructions for developers, or hints to tools and systems about how to handle a certain resource.
-- **Shared resources**: Annotations are used to provide additional information to anyone or anything interacting with your resources, defined in your Score file. This could be helpful instructions for developers, or hints to tools and systems about how to handle a certain resource.
+- **Shared resources**: Some resources may be also be used by or "shared" with other Workloads defined in different Score files or other deployment systems. The annotations could be used to track common IDs that may be used by other systems to know that this is the same instance of a resource.
 - **System-specific info**: Some systems and tools that interact with your Score resources might require certain metadata to be present to operate correctly, such as shared resources. Annotations provide a flexible way to supply this metadata.
 
 ### Annotations example
 
-The following is an example of using an annotation to provide additional metadata for a database service.
+The following is an example of using a Resource Annotation to provide additional metadata for a database resource.
 
 ```yml
 apiVersion: score.dev/v1b1
@@ -61,18 +61,11 @@ resources:
       annotations:
         "my.org/version": "0.1"
     type: postgres
-    properties:
-      host:
-        type: string
-        default: localhost
-        required: true
-      port:
-        default: 5432
 ```
 
 ### Shared resource example
 
-The following is an example of using an annotation to provide additional metadata for a shared resource.
+The following is an example of using a Resource Annotation supported by `score-humanitec` to indicate that the instance of a database resource is shared via a separate common `resId`.
 
 ```yml
 resources:
@@ -81,23 +74,15 @@ resources:
       annotations:
         score.humanitec.io/resId: shared.postgres-db
     type: postgres
-    properties:
-      host: localhost
-      port: 5432
 ```
 
-In this example, a shared PostgreSQL database is defined with the name `shared-db`.
-The annotation `score.humanitec.io/resId` is used to provide a unique identifier for this shared resource (`shared.postgres-db`).
-This identifier is used by the Humanitec system to map and manage this shared resource across multiple services or applications.
+In this example, a PostgreSQL database resource is defined with the name `shared-db`.
+The annotation `score.humanitec.io/resId` is used to provide an indication to Humanitec that this resources should be used with specific ID (`shared.postgres-db`).
 
-{{% alert %}}
-The type and properties of the resource would depend on the type of resource you are trying to define.
-{{% /alert %}}
+Any other Workload deployed into the same Humanitec application can also access the same database by adding the same annotation in their Score file.
 
-Now, any service or application that needs to use this shared resource can simply reference the identifier `shared.postgres-db`.
+## Resource Annotations vs. extension files
 
-## Annotations vs. extension files
+Resource Annotations are used to provide additional metadata as a hint for the individual Score file instead of using the extensions file.
 
-Annotations are used to provide additional metadata as a hint for the individual Score file instead of using the extensions file.
-
-It is recommended to use annotations instead of [extension files]({{< relref "../extensions/_index.md" >}}), as annotations help ensure consistency across your environments and deployments, since your Workload information is stored in one file.
+It is recommended to use Resource Annotations instead of [extension files]({{< relref "../extensions/_index.md" >}}), as annotations help ensure consistency across your environments and deployments, since your Workload information is stored in one file.