Skip to content

Commit 6a2ab7d

Browse files
Update docs/syntax/applies.md
Co-authored-by: Liam Thompson <[email protected]>
1 parent b23d2cc commit 6a2ab7d

File tree

1 file changed

+6
-18
lines changed

1 file changed

+6
-18
lines changed

docs/syntax/applies.md

Lines changed: 6 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -55,27 +55,15 @@ Both versioned and unversioned products use the same lifecycle tags, but only ve
5555

5656
## When and where to use `applies_to`
5757

58-
The `applies_to` tag can be added at different levels in the documentation: [page-level](#page-annotations), [section-level](#section-annotations), and [inline](#inline-applies-to). Each level uses slightly different syntax and serves a specific purpose:
59-
* [Page-level](#page-annotations) tagging is **mandatory** and must be included in the frontmatter. It defines the overall applicability of the page across products, deployments, and environments. For a complete list of supported keys and values, see the [frontmatter syntax guide](./frontmatter.md).
58+
✅ Use `applies_to` tags when features change state (`introduced`, `deprecated`, `removed`) or when availability differs across deployments and environments.
6059

61-
When the context differs from what was specified at the page level in a specific section or part of the page, it is appropriate to re-establish it.
60+
❌ Don't tag content-only changes like typos, formatting, or documentation updates that don't reflect feature lifecycle changes.
6261

63-
* [Section-level](#section-annotations) annotation lets you show or hide specific sections of content depending on the target context. This is helpful when only a part of a page varies between products or versions.
64-
* [Inline tagging](#inline-applies-to) allows fine-grained annotations within paragraphs or definition lists. It’s useful for highlighting the applicability of specific phrases, sentences, or properties without disrupting the surrounding content.
62+
The `applies_to` metadata can be added at different levels in the documentation:
6563

66-
### When to use `applies_to`
67-
68-
Every page must include a [page-level `applies_to`](#page-annotations) tag to clearly define its scope and availability.
69-
70-
Use version tagging when:
71-
* A feature is introduced (e.g., preview, beta, or ga)
72-
* A feature is deprecated (e.g., deprecated)
73-
* A feature is removed (e.g., removed)
74-
75-
You don’t need version tagging for:
76-
* Typos, formatting, or style changes
77-
* Long-standing features being documented for the first time
78-
* Content updates that don’t reflect a feature lifecycle change
64+
* [Page-level](#page-annotations) metadata is **mandatory** and must be included in the frontmatter. This defines the overall applicability of the page across products, deployments, and environments.
65+
* [Section-level](#section-annotations) annotations allow you to specify different applicability for individual sections when only part of a page varies between products or versions.
66+
* [Inline](#inline-applies-to) annotations allow fine-grained annotations within paragraphs or definition lists. This is useful for highlighting the applicability of specific phrases, sentences, or properties without disrupting the surrounding content.
7967

8068
### Page annotations
8169

0 commit comments

Comments
 (0)