From c763341fa68ec6c5c662c06897c7fbd63103948e Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Wed, 19 Feb 2025 07:36:51 -0800 Subject: [PATCH 1/2] Update style-guide.md for nested includes Make it clear that nested includes for version numbers are OK --- templates/style-guide.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/templates/style-guide.md b/templates/style-guide.md index 9c3aedefa..674f74fbd 100644 --- a/templates/style-guide.md +++ b/templates/style-guide.md @@ -449,7 +449,7 @@ To make sure includes are effective and easy to maintain, follow these practices - **Keep includes small and modular**: Write narrowly scoped snippets to maximize flexibility and reuse. - **Avoid branded product names in includes**: Use the full product name (e.g., "NGINX Instance Manager"), but avoid including the branded version (e.g., "F5 NGINX Instance Manager"). The branded name is required only on the first mention in a document; this is a context-specific rule. Includes, however, are designed to be context-agnostic—they should not rely on or assume any prior content—so including the branded name could repeat information unnecessarily in locations where it has already been introduced. - **Don't include headers**: Avoid adding H2 or other headers inside includes. These headers won't appear in the document's table of contents (TOC) and may not fit well with the surrounding content hierarchy. Add headers directly in the document instead. -- **Avoid nesting includes**: Don't place an include inside another include. While technically possible, it complicates reviews and maintenance. Use a flat structure for simplicity. +- **Avoid nesting includes**: Unless the intent is crystal clear, don't place an include inside another include. While technically possible, it complicates reviews and maintenance. Use a flat structure for simplicity. - **Don't start documents with includes**: The opening of a document is usually the introduction, which explains its purpose. Includes are reused text, so starting multiple documents with identical content could look odd, especially in search results. ## Guidelines for command-line operations @@ -503,6 +503,7 @@ this style guide over time. This guide uses the Major.Minor.Patch | Edition | Date | Lead Author(s) | Comments | |---------|---------------|----------------|-------------------------------------------------------| +| 1.10 | February 19, 2025 | Mike Jang | Clarify use of nested includes. | | 1.9 | December 10, 2024 | Mike Jang | Specify the use of "license" when writing about the JWT token associated with licensed versions of NGINX. | | 1.8 | December 4, 2024 | Jon Torre | Clarify that heading text must not contain a link to other pages. | | 1.7 | November 20, 2024 | Mike Jang | Specify "includes" must be in at leat two locations. | From 310077651a4c86ebe68258d64f79b003a48e5eb6 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Wed, 19 Feb 2025 09:30:35 -0800 Subject: [PATCH 2/2] Update templates/style-guide.md --- templates/style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/templates/style-guide.md b/templates/style-guide.md index 674f74fbd..410e4e937 100644 --- a/templates/style-guide.md +++ b/templates/style-guide.md @@ -449,7 +449,7 @@ To make sure includes are effective and easy to maintain, follow these practices - **Keep includes small and modular**: Write narrowly scoped snippets to maximize flexibility and reuse. - **Avoid branded product names in includes**: Use the full product name (e.g., "NGINX Instance Manager"), but avoid including the branded version (e.g., "F5 NGINX Instance Manager"). The branded name is required only on the first mention in a document; this is a context-specific rule. Includes, however, are designed to be context-agnostic—they should not rely on or assume any prior content—so including the branded name could repeat information unnecessarily in locations where it has already been introduced. - **Don't include headers**: Avoid adding H2 or other headers inside includes. These headers won't appear in the document's table of contents (TOC) and may not fit well with the surrounding content hierarchy. Add headers directly in the document instead. -- **Avoid nesting includes**: Unless the intent is crystal clear, don't place an include inside another include. While technically possible, it complicates reviews and maintenance. Use a flat structure for simplicity. +- **Avoid nesting includes**: If there’s another way to achieve the same outcome, avoid nesting includes. While technically possible, it complicates reviews and maintenance. Use a flat structure for simplicity. - **Don't start documents with includes**: The opening of a document is usually the introduction, which explains its purpose. Includes are reused text, so starting multiple documents with identical content could look odd, especially in search results. ## Guidelines for command-line operations