[Style guide] Update permission and product scannability information …

…(#50986)

Co-authored-by: hubwriter <[email protected]>

content/contributing/style-guide-and-content-model/contents-of-a-github-docs-article.md

@@ -47,25 +47,6 @@ Titles can be challenging. Use these general guidelines to help create clear, he
   - What specific words do we need to include in the title or intro so that folks don’t mistake it for content about a different product?
 - Think about how the title will look in production.
 
-## Product callout
-
-Use the product callout when a feature is available in specific products only and that availability cannot be conveyed by versioning alone. For example, if a feature is available for GHEC and GHES, you can version content about the feature for GHEC and GHES only. If a feature is available for Pro, Team, GHEC, and GHES (but not Free), use a product callout to convey that availability.
-
-All product callouts are stored as reusables in [`gated-features`](https://github.com/github/docs/tree/main/data/reusables/gated-features) and added in YAML frontmatter for relevant articles.
-
-### How to write a product callout
-
-- Product callouts follow a strict format, clearly identifying the feature and which products it’s available in.
-- Product callouts also include a link to "GitHub’s products” and occasionally to another relevant article.
-- Examples:
-  - [Feature name] is available in [product(s)]. For more information, see "GitHub’s products.”
-  - [Feature name] is available in public repositories with [free product(s)], and in public and private repositories with [paid products]. For more information, see "GitHub’s products.”
-
-### Examples of articles with product callouts
-
-Check the source files and `gated-features` to see how source content is written.
-- [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule)
-
 ## Intro
 
 The top of every page has an intro that provides context and sets expectations, allowing readers to quickly decide if the page is relevant to them. Intros also are displayed in search results to provide contextual information to help readers choose a result.
@@ -104,6 +85,25 @@ Occasionally, it's relevant to mention required permissions in conceptual conten
 
 - Article with single permissions statement for multiple procedures: [AUTOTITLE](/enterprise-cloud@latest/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise)
 
+## Product callout
+
+Use the product callout when a feature is available in specific products only and that availability cannot be conveyed by versioning alone. For example, if a feature is available for GHEC and GHES, you can version content about the feature for GHEC and GHES only. If a feature is available for Pro, Team, GHEC, and GHES (but not Free), use a product callout to convey that availability.
+
+All product callouts are stored as reusables in [`gated-features`](https://github.com/github/docs/tree/main/data/reusables/gated-features) and added in YAML frontmatter for relevant articles.
+
+### How to write a product callout
+
+- Product callouts follow a strict format, clearly identifying the feature and which products it’s available in.
+- Product callouts also include a link to "GitHub’s products” and occasionally to another relevant article.
+- Examples:
+  - [Feature name] is available in [product(s)]. For more information, see "GitHub’s products.”
+  - [Feature name] is available in public repositories with [free product(s)], and in public and private repositories with [paid products]. For more information, see "GitHub’s products.”
+
+### Examples of articles with product callouts
+
+Check the source files and `gated-features` to see how source content is written.
+- [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule)
+
 ## Tool switcher
 
 Some articles have content that varies depending on what tool someone uses to complete a task, such as the {% data variables.product.prodname_cli %} or {% data variables.product.prodname_desktop %}. For most content, the same conceptual or procedural information will be accurate for multiple tools. However, if the only way to make information clear and accurate is by distinguishing content by tool, use the tool switcher. Do not use the tool switcher just to show examples in different languages. Only use the tool switcher if the tasks or concepts change based on what tool someone uses. For more information, see "[AUTOTITLE](/contributing/writing-for-github-docs/creating-tool-switchers-in-articles)".

content/contributing/style-guide-and-content-model/style-guide.md

@@ -699,6 +699,33 @@ When introducing a list, avoid short, nonspecific sentences using terms like “
 - There are several articles that provide an introduction to {% data variables.product.prodname_dotcom %}. See the following:
 - SMS authentication is supported in 50 countries. These include:
 
+## Permission statements and product callouts
+
+Use permission statements and product callouts to communicate tasks that require specific roles or products to complete.
+
+- [**Permissions statements**](/contributing/style-guide-and-content-model/contents-of-a-github-docs-article#permission-statements): The role required to take an action or do a task described in the article. Example: "Enterprise owners."
+- [**Product callout**](/contributing/style-guide-and-content-model/contents-of-a-github-docs-article#product-callout): The product or products required to take an action or do a task described in the article. Example: "Organization and enterprise accounts with a subscription to {% data variables.product.prodname_copilot_business_short %}."
+
+Together, permission statements and product callouts tell readers who can use the feature being described in an article.
+
+### Guidelines for creating scannable product callouts
+
+#### Define permissions versus product requirements
+
+Consider what information belongs in a permission statement or a product callout.
+
+For example, when creating permissions and product callouts for the article "[AUTOTITLE](/free-pro-team@latest/copilot/managing-github-copilot-in-your-organization/managing-policies-and-features-for-copilot-in-your-organization)," the permission statement would answer "What role can manage policies and features for {% data variables.product.prodname_copilot %} in an organization?" And the product callout would answer "What {% data variables.product.prodname_copilot_short %} subscriptions do users need to manage {% data variables.product.prodname_copilot_short %} policies and features for an organization?"
+
+#### Focus on key information, not explanations
+
+Permission statements and product callouts need to communicate who can perform a task and what product is required. They do not need to explain why a role or product is required.
+
+If multiple roles or products apply to a permission statement or product callout, format them using an unordered list. You can introduce complex permission statements and product callouts with a sentence, but always try to use as few words as necessary to communicate who can do what the article is about.
+
+#### Use inline links
+
+You can use inline links to provide more information about a role or product. The linked text must match the link destination so that it is clear where following the link will lead to.
+
 ## Placeholders
 
 Style any placeholder text in all caps. If a placeholder is multiple words, connect the words with dashes (kebab-case). If you use a placeholder, explain what someone might replace it with. This helps people modify examples to fit their needs and helps identify placeholders for people who use assistive technology.