diff --git a/docs/features/software-catalog/descriptor-format.md b/docs/features/software-catalog/descriptor-format.md
index ff2f92beab..7171e0c7b8 100644
--- a/docs/features/software-catalog/descriptor-format.md
+++ b/docs/features/software-catalog/descriptor-format.md
@@ -98,7 +98,7 @@ See below for details about these fields.
 The descriptor format supports substitutions using `$text`, `$json`, and
 `$yaml`.
 
-Placeholders like `$json: https://example.com/entity.json` are substituded by
+Placeholders like `$json: https://example.com/entity.json` are substituted by
 the content of the referenced file. Files can be referenced from any configured
 integration similar to locations by passing an absolute URL. It's also possible
 to reference relative files like `./referenced.yaml` from the same location.
diff --git a/docs/features/software-catalog/well-known-annotations.md b/docs/features/software-catalog/well-known-annotations.md
index 7d16427a3c..3627c74b9a 100644
--- a/docs/features/software-catalog/well-known-annotations.md
+++ b/docs/features/software-catalog/well-known-annotations.md
@@ -238,22 +238,9 @@ annotation, with the same value format.
 
 ### backstage.io/definition-at-location
 
-This annotation allowed to load the API definition from another location. Now
-placeholders can be used instead:
-
-```
-apiVersion: backstage.io/v1alpha1
-kind: API
-metadata:
-  name: petstore
-  description: The Petstore API
-spec:
-  type: openapi
-  lifecycle: production
-  owner: petstore@example.com
-  definition:
-    $text: https://petstore.swagger.io/v2/swagger.json
-```
+This annotation allowed to load the API definition from another location. Use
+[substitution](./descriptor-format.md#substitutions-in-the-descriptor-format)
+instead.
 
 ## Links