Merge branch 'main' into nap-release-5.7

ADubhlaoich · web-flow · commit 8faf586ce8f6 · 2025-06-24T12:43:35.000+01:00
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,9 +1,10 @@
 # Contributing guidelines
 
-The following is a set of guidelines for community contributions to this
-project. We really appreciate your desire to contribute!
+The following is a set of guidelines for community contributions to this project. 
 
-If you are an F5 employee, see the following additional guidance [For F5 Employees](./F5-NGINX-team-notes.md).
+We really appreciate your desire to contribute!
+
+If you are an F5 employee, see the following additional guidance on [Maintainers etiquette](/documentation/maintainers-etiquette.md).
 
 ## Table of contents
 
@@ -12,8 +13,8 @@ If you are an F5 employee, see the following additional guidance [For F5 Employe
 - [Open a Discussion](#open-a-discussion)
 - [Submit a Pull Request](#submit-a-pull-request)
   - Review our [Git style guide](#git-style-guide)
-  - Review our Documentation [style guide](./templates/style-guide.md)
-  - Review our [Contributing guidelines for writers](./CONTRIBUTING_DOCS.md)
+  - Review the [Writing style guide](/documentation/style-guide.md)
+  - Review [Managing content with Hugo](/documentation/writing-hugo.md)
 - [Issue Lifecycle](#issue-lifecycle)
 - [Additional NGINX documentation](#additional-nginx-documentation)
 - [F5 Contributor License Agreement (CLA)](#f5-contributor-license-agreement)
@@ -51,6 +52,7 @@ our documentation as described in our [support](./SUPPORT.md) page.
 ### Git style guide
 
 - Keep a clean, concise and meaningful Git commit history on your branch, rebasing locally and squashing before you submit a PR
+- We use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) formatting.
 - Follow the guidelines of writing a good commit message as described here <https://chris.beams.io/posts/git-commit/>
   and summarized in the next few points:
 
diff --git a/archetypes/landing-page.md b/archetypes/landing-page.md
@@ -0,0 +1,49 @@
+---
+# The title is the product name
+title: 
+# The URL is the base of the deployed path, becoming "docs.nginx.com/<url>/<other-pages>"
+url: 
+# The cascade directive applies its nested parameters down the page tree until overwritten
+cascade:
+  # The logo file is resolved from the theme, in the folder /static/images/icons/
+  logo:
+# The subtitle displays directly underneath the heading of a given page
+nd-subtitle: 
+# Indicates that this is a custom landing page
+nd-landing-page: true
+# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this
+nd-content-type: landing-page
+# Intended for internal catalogue and search, case sensitive:
+# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit
+nd-product:
+---
+
+## About
+[//]: # "These are Markdown comments to guide you through document structure. Remove them as you go, as well as any unnecessary sections."
+[//]: # "Use underscores for _italics_, and double asterisks for **bold**."
+[//]: # "Backticks are for `monospace`, used sparingly and reserved mostly for executable names - they can cause formatting problems. Avoid them in tables: use italics instead."
+
+[//]: # "This initial section introduces the product to a reader: give a short 1-2 sentence summary of what the product does and its value to the reader."
+[//]: # "Name specific functionality it provides: avoid ambiguous descriptions such as 'enables efficiency', focus on what makes it unique."
+
+## Featured content
+[//]: # "You can add a maximum of three cards: any extra will not display."
+[//]: # "One card will take full width page: two will take half width each. Three will stack like an inverse pyramid."
+[//]: # "Some examples of content could be the latest release note, the most common install path, and a popular new feature."
+
+{{<card-layout>}}
+  {{<card-section showAsCards="true" isFeaturedSection="true">}}
+    {{<card title="<some-title>">}}
+      <!-- Each description should be roughly 10 words or less. -->
+    {{</card>}}
+    <!-- The titleURL and icon are both optional -->
+    <!-- Lucide icon names can be found at https://lucide.dev/icons/ -->
+    {{<card title="<some-title>" titleUrl="<some-url>" icon="<some-lucide-icon>">}}
+      <!-- Each description should be roughly 10 words or less. -->
+    {{</card>}}
+  {{</card-section>}}
+{{</card-layout>}}
+
+## Other content 
+
+[//]: # "You can add any extra content for the page here, such as additional cards, diagrams or text."
diff --git a/content/agent/_index.md b/content/agent/_index.md
@@ -3,7 +3,7 @@ title: NGINX Agent
 url: /nginx-agent/
 cascade:
   logo: NGINX-product-icon.png
-  banner:
+  nd-banner:
     enabled: true
     type: deprecation
     start-date: 2025-05-29
diff --git a/content/controller/_index.md b/content/controller/_index.md
@@ -6,7 +6,7 @@ weight: 2100
 cascade:
   logo: "NGINX-Controller-product-icon-RGB.svg"
   noindex: true
-  banner:
+  nd-banner:
     enabled: true
     type: deprecation
     md: _banners/eos-cltr.md
diff --git a/content/mesh/_index.md b/content/mesh/_index.md
@@ -8,7 +8,7 @@ description: 'NGINX Service Mesh is a fully integrated lightweight service mesh
 url: /nginx-service-mesh/
 cascade:
   noindex: true
-  banner:
+  nd-banner:
     enabled: true
     type: deprecation
     md: _banners/eos-mesh.md
diff --git a/content/ngf/_index.md b/content/ngf/_index.md
@@ -3,7 +3,7 @@ title: NGINX Gateway Fabric
 url: /nginx-gateway-fabric/
 cascade:
   logo: NGINX-Gateway-Fabric-product-icon.png
-  banner:
+  nd-banner:
     enabled: true
     type: deprecation
     start-date: 2025-05-30
diff --git a/content/nim/deploy/_index.md b/content/nim/deploy/_index.md
@@ -4,7 +4,7 @@ description:
 weight: 20
 url: /nginx-instance-manager/deploy/
 cascade:
-  banner:
+  nd-banner:
     enabled: true
     type: deprecation
     md: _banners/upgrade-r33.md
diff --git a/documentation/README.md b/documentation/README.md
@@ -2,7 +2,7 @@
 
 This directory contains the documentation for the NGINX Documentation repository.
 
-It's used by the DocOps team to record how we configure our tools and instructions for certain precise tasks.
+It's used by the DocOps team to record how we use our tools and instructions for common tasks.
 
 There's also documentation around our ways of working, and ideas of significance wider than the scope of an issue or pull request.
 
@@ -12,4 +12,9 @@ If you're interested in contributing to the [NGINX documentation website](https:
 
 ## Topics
 
+- [Contributing closed content](/documentation/closed-contributions.md)
+- [Information architecture heuristics](/documentation/ia-heuristics.md)
+- [Maintainers etiquette](/documentation/maintainers-etiquette.md)
+- [Managing content with Hugo](/documentation/writing-hugo.md)
 - [Proposals](/documentation/proposals/README.md)
+- [Writing style guide](/documentation/style-guide.md)
diff --git a/documentation/closed-contributions.md b/documentation/closed-contributions.md
@@ -1,4 +1,4 @@
-# Contributing guidelines for closed content
+# Contributing closed content
 
 This document describes the process for authoring "closed content", which is content of a sensitive nature that cannot be publicised before release.
 
diff --git a/documentation/ia-heuristics.md b/documentation/ia-heuristics.md
@@ -0,0 +1,122 @@
+# Information architecture heuristics
+
+This document describes some of the heuristics that the NGINX DocOps team uses to examine information architecture.
+
+It is intended as reference information for discussions and work management artefacts (Such as reports or issues).
+
+These heuristics are an adaptation of work done by [Abby Covert](https://abbycovert.com/).
+
+## Overview
+
+| Name                            | Description                                             |
+| --------------------------------| ------------------------------------------------------- |
+| [Accessible](#accessible)       | Where and how is information being accessed?            |
+| [Clear](#clear)                 | Does the user have clear and essential information?     |
+| [Communicative](#communicative) | Can the user anticipate content based on the structure? |
+| [Controllable](#controllable)   | Does the user retain agency throughout a process?       |
+| [Credible](#credible)           | Can the user trust the information?                     |
+| [Delightful](#delightful)       | Does the user experience feel fun and easy?             |
+| [Findable](#findable)           | Is information easily discoverable for users?           |
+| [Learnable](#learnable)         | Is navigating information familiar to the user?         |
+| [Useful](#useful)               | Does the information lead to the intended result?       |
+| [Valuable](#valuable)           | Is the information provided valuable, and how?          |
+
+## Accessible
+
+- Is the information accessible through the most common mediums and devices?
+- How does the information behave when perceived through other means?
+- Does the information match or exceed any compliance guidelines?
+
+_Accessible_ concerns how navigable the information is by users. A user should be able to traverse content using any input method, browser or device desired.
+
+If critical details are not available to a user based on the method they use to access information, it is not accessible.
+
+## Clear
+
+- Is the information easy to understand and explain?
+- How does the structure reduce noise for the user journey?
+- Does the structure fulfil the expectations of the user persona?
+
+_Clear_ concerns whether or not the information aligns with the user's background and if it is devoid of distractions.
+
+The structure should streamline the user experience for navigating and reading information, allowing them to understand intent without ambiguity.
+
+## Communicative
+
+- Is the structure effective in recognising the user's state?
+- Are the structure and information consistent?
+- How does the structure support the information being shared?
+
+_Communicative_ concerns the effectiveness of the user journey.
+
+A user should be able to make informed decisions about their actions in a timely manner, and able to orient themselves within the structure.
+
+## Controllable
+
+- Is the process state clear for a task from the information?
+- Can the user anticipate errors or mistakes?
+- Are important controls clearly marked?
+
+_Controllable_ concerns where information leads a user and how that affects them. They should be aware of the consequences when following instructions.
+
+If a document leaves a user in an inoperable state, it is not controllable. This could be caused by incomplete information, or information split across multiple places reliant on context to finish a task.
+
+## Credible
+
+- Is the tone and focus of the information consistent?
+- Can the user trust the accuracy of the information?
+- When and how is information updated?
+
+_Credible_ concerns trust in the information provided. If the tone or presentation of information is unclear, it may build uncertainty for a user.
+
+The credibility of information can be considered based on where it exists in overall structure, and indicators of how recently it was updated.
+
+## Delightful
+
+- Does the structure make a task feel easy?
+- Is supporting information provided where useful?
+- How does the information exceed expectation?
+
+_Delightful_ is the step beyond fulfilling basic expectations.
+
+This concerns overall quality of the user experience, such as smooth transitions between mediums and useful recommendations.
+
+## Findable
+
+- Is it easy for users to locate information?
+- What methods are available for users to discover information?
+- Does the information translate effectively for non-human users?
+
+_Findable_ concerns how a user discovers and traverses your collection of information.
+
+This can reflect the navigation tree or sitemap of a website, as well as contextual links between information. It is also related to how the information is percieved through search mechanisms.
+
+## Learnable
+
+- Is the structure clear and easy to understand?
+- Is the structure memorable?
+- How does the structure help someone understand the information?
+
+_Learnable_ concerns whether or not the structure makes sense to a user, and how it shapes their mental model of information.
+
+This can be examined from multiple angles, such as if the structure is consistent across products, or if it matches their journey.
+
+## Useful
+
+- Is the information correct?
+- Is the information complete?
+- Does the information serve both existing and new users?
+
+_Useful_ concerns the baseline for the user experience by enabling them to complete tasks.
+
+Information is useful if it accomodates new and old users, and if it enables them to concisely navigate through context with confidence.
+
+## Valuable
+
+- Is the information desireable to the user?
+- Does it fulfill expectations across all channels?
+- How is success quantified?
+
+_Valuable_ concerns if the information is desireable, and if the story presented compelling to the user.
+
+This can be emphasized by highlighting information that aligns with the user's mental models and the tangible benefits of a particular use case.
diff --git a/documentation/maintainers-etiquette.md b/documentation/maintainers-etiquette.md
@@ -1,24 +1,21 @@
-# For F5/NGINX Employees
+# Maintainers etiquette
 
-This repository is public, and we do as much of our work as possible in the public as a commitment to open source.
-
-Before new content is published at https://docs.nginx.com, it must be committed to this `documentation` repository. 
-
-If you are an F5 employee unable to assign yourself as an owner of an issue or a reviewer of a pull request, ask a member of the NGINX documentation team for help.
-
-If your content cannot be publicized before release, it is handled differently: read the [Contributing guidelines for closed content](/CLOSED_CONTRIBUTIONS.md) document.
+This document is intended for the maintainers of the repository, who are any F5/NGINX employees that contribute to it.
 
 We encourage you to work with community contributors. If you participate in PRs, issues, discussions, and more, follow these guidelines:
 
 - Follow the [Code of Conduct](./CODE_OF_CONDUCT.md).
 - Be helpful. We want to encourage people who contribute to continue.
-  - If you need to say "no," here's [an example](https://github.com/nginx/documentation/pull/307#issuecomment-2748521932) of how we interact with the community.
+  - If you need to say "no," here's [an example](https://github.com/nginx/documentation/pull/307#issuecomment-2748521932) of how to interact with the community.
 - Avoid references and links to internal content. 
-- Do not include information about future releases, changes, or features, unless
-  specifically authorized.
-- Do not include anything that even resembles PII.
+- Do not include information about future releases, changes, or features, unless specifically authorized.
+- Do not include anything that resembles PII.
 - Do not include information that is proprietary to and/or private within F5/NGINX.
 
+This repository is public, and we do as much of our work as possible in the public as a commitment to open source.
+
 As an F5/NGINX employee, if you have a GitHub account, you should be able to clone these repositories.
 
+If your content cannot be visible before release, you should read the [Contributing guidelines for closed content](/CLOSED_CONTRIBUTIONS.md) document.
+
 To protect F5/NGINX, the ability to merge pull requests is strictly limited to employees of F5/NGINX.
diff --git a/documentation/style-guide.md b/documentation/style-guide.md
diff --git a/documentation/writing-hugo.md b/documentation/writing-hugo.md
@@ -1,12 +1,12 @@
-# Contributing guidelines for writers
+# Managing content with Hugo
 
 This page describes our guidelines on using [Hugo](https://gohugo.io/) to write documentation.
 
 You will need [git](https://git-scm.com/) to interact with the repository and files: the content itself is written in Markdown.
 
 Our workflow is to develop content locally, then submit a pull request once we've done our initial draft and editing passes.
 
-If you're an employee of F5/NGINX, also read [For F5/NGINX Employees](./F5-NGINX-team-notes.md).
+For guidance around how to write content, please check [the style guide](/documentation/style-guide.md).
 
 ## Setup
 

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Contributing guidelines for closed content`
	`1`	`+# Contributing closed content`
`2`	`2`
`3`	`3`	`This document describes the process for authoring "closed content", which is content of a sensitive nature that cannot be publicised before release.`
`4`	`4`