Update versioning guidance (github#23793)

Author: mattpollard

contributing/liquid-helpers.md

@@ -8,11 +8,19 @@ Note: If you are an open source contributor, you should not worry about versioni
 
 ## Versioned documentation
 
-We provide versioned documentation for users of GitHub.com, Enterprise Server, and GitHub AE (with more to come). If multiple versions of a Docs site page exist, readers can choose the version from the version picker at the top of the page.
+We provide versioned documentation for users of GitHub.com plans and Enterprise Cloud, Enterprise Server, and GitHub AE. If multiple versions of a page exist on the site, readers can choose the version from the version picker at the top of the page.
 
-### Dotcom
+### GitHub.com
 
-Documentation for Dotcom has one version: the `free-pro-team@latest` version. The short name is `fpt`.
+Documentation for GitHub.com has two possible versions:
+
+#### Free, Pro, or Team plans
+
+For Free, Pro, or Team plans on GitHub.com, use `free-pro-team@latest`. The short name is `fpt`.
+
+#### Enterprise Cloud
+
+For GitHub Enterprise Cloud, use `enterprise-cloud@latest`. The short name is `ghec`.
 
 ### Enterprise Server
 
@@ -22,7 +30,7 @@ The versions are named `enterprise-server@<release>`. The short name is `ghes`.
 
 ### GitHub AE
 
-Documentation for GitHub AE is similar to Dotcom: we only offer one version of the content for the product, the `github-ae@latest` version. The short name is `ghae`.
+Versioning for GitHub AE uses the `github-ae@latest` version. The short name is `ghae`.
 
 ## Versioning in the YAML frontmatter
 
@@ -34,7 +42,8 @@ If you define multiple products in the `versions` key within a page's YAML front
 
 Important notes:
 
-* Make sure to use `ifversion` and not `if`. A test will fail if an `if` statement is used for versioning.
+* Use `ifversion` for product-based versioning. If you use `if` for product-based versioning, a test will fail.
+* Use `if` for [feature-based versioning](#feature-based-versioning).
 * Make sure to use `elsif` and not `else if`. Liquid does not recognize `else if` and will not render content inside an `else if` block.
 
 ### Comparison operators
@@ -74,17 +83,6 @@ When **at least one** operand must be true for the condition to be true, use the
 
 Do **not** use the operators `&&` or `||`. Liquid does not recognize them, and the content will not render in the intended versions.
 
-### Versioning content for _future_ releases of GitHub AE
-
-If your content describes a feature that will be included in the next release of GitHub AE, you can use a placeholder version string, `ghae-next`. Before the next GitHub AE release, we will run a script to replace the placeholder with `ghae`.
-
-For example, you can use this logic for a feature that's shipping on GitHub.com and will also be available in a future update to GitHub AE:
-```
-{% ifversion fpt or ghae-next %}This is a brand new feature, the likes of which have never been seen at this company before!{% endif %}
-```
-After the feature becomes available in GitHub AE and we run the replacement script, this statement will become:
-```
-{% ifversion fpt or ghae %}This is a brand new feature, the likes of which have never been seen at this company before!{% endif %}
-```
+### Feature-based versioning
 
-`ifversion` tags can also support `ghae-issue-<number>` as an additional way to version content more granularly for upcoming GitHub AE releases.
+You can define an arbitrarily named feature and associate specific product versions with that named feature using feature-based versioning. When you use the named version in a Liquid conditional block, the versions that you associate will apply to the content within the block. If the versioning for the feature changes, you can update one file instead of every individual Liquid tag.. For more information, see [data/features/README.md](/data/features).

data/README.md

@@ -4,9 +4,13 @@ This directory contains data files that are parsed and made available to pages i
 
 All YML and Markdown files in this directory are configured to be translated on Crowdin by default.
 
+## Features
+
+Feature files are used for feature-based versioning. See [features/README.md](features/README.md).
+
 ## Glossaries
 
-Glossary files are used by our Crowdin integration. See [glossaries/README.md](glossaries/README.md).
+We provide a customer-facing glossary on the site. Other glossary files are used by our Crowdin integration. See [glossaries/README.md](glossaries/README.md).
 
 ## GraphQL
 
@@ -30,4 +34,8 @@ Webhook payload JSON files are used in the [`webhook events docs`](../content/de
 
 ## Learning Tracks
 
-Learning tracks are a collection of articles that help you master a particular subject. See [learning-tracks/README.md](learning-tracks/README.md).
+Learning tracks are a collection of articles that help you master a particular subject. See [learning-tracks/README.md](learning-tracks/README.md).
+
+## Versioning
+
+Many YAML files in this directory's subdirectories, like [features](features), [glossaries](glossaries), [variables](variables), and [learning tracks](learning-tracks), as well as Markdown files within the [reusables](reusables) directory, can include YAML versioning or Liquid versioning within Markdown strings. See the README.md files in the subdirectories for details.

data/glossaries/README.md

@@ -3,5 +3,6 @@
 The following files comprise our [Crowdin Glossary](https://support.crowdin.com/glossary/):
 
 * `external.yml` contains customer-facing glossary entries.
+  * Strings within `external.yml` support Liquid conditionals. See [contributing/liquid-helpers.md](/contributing/liquid-helpers.md).
 * `internal.yml` contains entries used by translators only. These terms are displayed in the Crowdin UI to give translators additional context about what they're translating, plus a suggested localized string for that term.
 * `candidates.yml` contains terms that should potentially be in either the internal or external glossary but haven't been defined yet.

data/learning-tracks/README.md

@@ -33,7 +33,10 @@ Versioning for learning tracks is processed at page render time. The code lives
 
 Liquid conditionals do **not** have to be used for versioning in the YAML file for guides. Only the learning track guides that apply to the current version will be rendered automatically. If there aren't any tracks with guides that belong to the current version, the learning tracks section will not render at all.
 
-Explicit versioning within a product's learning tracks YML data is supported as well. For example:
+Explicit versioning within a product's learning tracks YML data is supported as well. The format and allowed values are the same as the [frontmatter versions property](/content#versions).
+
+For example:
+
 ```
 learning_track_name:
   title: 'Learning track title'
@@ -45,6 +48,7 @@ learning_track_name:
    - /path/to/guide1
    - /path/to/guide2
 ```
+
 If the `versions` property is not included, it's assumed the track is available in all versions.
 
 ## Schema enforcement

data/reusables/README.md

@@ -11,3 +11,7 @@ The *path* and *filename* of each Markdown file determines what its path will be
 For example, a file named `/data/reusables/foo/bar.md` will be accessible as `{% data reusables.foo.bar %}` in pages.
 
 Reusable files are divided generally into directories by task. For example, if you're creating a reusable string for articles about GitHub notifications, you'd add it in the directory `data/reusables/notifications/` in a file named `data/reusables/notifications/your-reusable-name.md`. The content reference you'd add to the source would look like `{% data reusables.notifications.your-reusable-name %}`.
+
+## Versioning
+
+Reusables can include Liquid conditionals to conditionally render content depending on the current version being viewed. See [contributing/liquid-helpers.md](/contributing/liquid-helpers.md).