feat: Replace existing archetypes with three new discrete types (#97)

NGINX documentation broadly follows the Diataxis model, and we have
specific conventions around certain types of documents.

This commit pares the exisiting Hugo archetype down to three that are
closely related: how-to, concept and tutorial. Outside of providing
page-specific information architecture, these templates include our
updated frontmatter formatting and parameter, and inline guidance
on how we prefer to use Markdown formatting and Hugo shortcodes.

There will be additional work of this nature in the future, once more
specialised content types have been identified and consensus has been
reached on what their precise style should be.

Author: ADubhlaoich

archetypes/api.md

@@ -1,44 +1,74 @@
 ---
+# We use sentence case and present imperative tone
 title: "{{ replace .Name "-" " " | title }}"
-date: {{ .Date }}
-# Change draft status to false to publish doc
-draft: true
-# Description
-# Add a short description (150 chars) for the doc. Include keywords for SEO. 
-# The description text appears in search results and at the top of the doc.
-description: ""
-# Assign weights in increments of 100
-weight: 
-toc: true
-tags: [ "docs" ]
-# Create a new entry in the Jira DOCS Catalog and add the ticket ID (DOCS-<number>) below
+# Weights are assigned in increments of 100: determines sorting order
+weight: i00
+# Creates a table of contents and sidebar, useful for large documents
+toc: false
+# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this
+type: concept
+# Intended for internal catalogue and search, case sensitive:
+# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit
+product:
+# Intended for internal catalogue
 docs: "DOCS-000"
-# Taxonomies
-# These are pre-populated with all available terms for your convenience.
-# Remove all terms that do not apply.
-categories: ["installation", "platform management", "load balancing", "api management", "service mesh", "security", "analytics"]
-doctypes: ["concept"]
-journeys: ["researching", "getting started", "using", "renewing", "self service"]
-personas: ["devops", "netops", "secops", "support"]
-versions: []
-authors: []
 ---
- 
-## Overview
 
-Briefly describe the goal of this document, that is, what the user will learn or accomplish by reading what follows.
+[//]: # "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."
 
-## Concept 1 - format as a noun phrase
+[//]: # "Begin each document with a sentence or two explaining what the purpose of the guide is, and what high-level actions to expect. No need to adhere precisely the example text given anywhere in this template."
 
-This is where you explain the concept. Provide information that will help the user understand what the element/feature is and how it fits into the overall product.
+This guide provides an overview of <concept>, which is used <for/in> <action 1>, <action 2> and <action 3>.
 
-Organize content in this section with H3 and H4 headings.
+It is an example of a <other concept>, and is closely related to <third concept>.
 
-## Concept 2 - format as a noun phrase
+---
+
+## Background
+
+[//]: # "Explain what the concept is. If possible, relate it to another commonly known concept or software."
+[//]: # "This relates the new idea to the reader using their existing knowledge, helping their understanding of it and thus what its purpose is in context."
+
+---
+
+## Use cases
+
+[//]: # "Name the individual use case sections after the actual use case itself, e.g "Route traffic between applications"
+
+### Use case 1
+
+[//]: # "A description for a use case should be a high level outline of a particular problem, then explain how the subject concept is the solution for the issue."
+
+[//]: # "If it helps, include a diagram of some kind. Ensure your description provides all the context required, however: a diagram is an aid to explain things, not a replacement."
 
-## Concept 3 - format as a noun phrase
+```mermaid
+# You can use Mermaid to draw diagrams in a codeblock with mermaid as the language.
+# Read their documentation for usage: https://mermaid.js.org/intro/
+```
+
+Starting from the <top/left> of the diagram, you can see that <thing> is connected to <other thing>: this relationship is established when configuring <parameter> as part of <file name>.
+
+[//]: # "End a particular use case section with links to other pages, such as instructional documentation, other concepts, or reference information (Such as API specifications)."
+
+- [Additional reading 1](some-external-link)
+- [Additional reading 2]({{< ref "/some/internal/link.md" >}})
+- Additional reading 3
+
+### Use case 2
+
+---
+
+## Conclusion
+
+[//]: # "Summarize everything that the reader will have learned by reading this entire concept document."
+[//]: # "It should fulfill the promise made by the introductory paragraph at the top of the document."
+[//]: # "Since each use case provides links to additional documents, you may not need to link to more,"
+[//]: # "or even include the final 'See also' section."
+
+---
 
-## What's Next
+## See also
 
-- Provide up to 5 links to related topics (optional).
-- Format as a bulleted list.
+[//]: # "Link to related documents, such as concepts, reference material or similar use cases."

archetypes/blog.md

@@ -1,79 +1,90 @@
 ---
+# We use sentence case and present imperative tone
 title: "{{ replace .Name "-" " " | title }}"
-date: {{ .Date }}
-# Change draft status to false to publish doc.
-draft: true
-# Description
-# Add a short description (150 chars) for the doc. Include keywords for SEO. 
-# The description text appears in search results and at the top of the doc.
-description: ""
-# Assign weights in increments of 100
-weight: 
-toc: true
-tags: [ "docs" ]
-# Create a new entry in the Jira DOCS Catalog and add the ticket ID (DOCS-<number>) below
+# Weights are assigned in increments of 100: determines sorting order
+weight: i00
+# Creates a table of contents and sidebar, useful for large documents
+toc: false
+# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this
+type: how-to
+# Intended for internal catalogue and search, case sensitive:
+# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit
+product:
+# Intended for internal catalogue
 docs: "DOCS-000"
-# Taxonomies
-# These are pre-populated with all available terms for your convenience.
-# Remove all terms that do not apply.
-categories: ["installation", "platform management", "load balancing", "api management", "service mesh", "security", "analytics"]
-doctypes: ["task"]
-journeys: ["researching", "getting started", "using", "renewing", "self service"]
-personas: ["devops", "netops", "secops", "support"]
-versions: []
-authors: []
+---
+
+[//]: # "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."
+
+[//]: # "Begin each document with a sentence or two explaining what the purpose of the guide is, and what high-level actions to expect. No need to adhere precisely the example text given anywhere in this template."
+
+This guide explains how to <X> with <Y>. In involves the use of <A>, <B> and <C>, demonstrating how <X> works with an example <Z>.
 
 ---
 
-## Overview
+## Before you begin
+
+[//]: # "List everything someone will need installed or configured before it's required. Link directly to installation guides where possible."
+
+To complete this guide, you will need the following prerequisites:
+
+- [Requirement 1](some-external-link)
+- [Requirement 2]({{< ref "/some/internal/link.md" >}})
+- Requirement 3
+
+[//]: # "Note the style of link for requirement two: keep the markdown extension. Links are resolved from the root of the documentation folder, often /site."
 
-Briefly describe the goal of this document, that is, what the user will learn or accomplish by reading what follows.
+---
+
+## Step 1
 
-Introduce and explain any new concepts the user may need to understand before proceeding.
+[//]: # "Explain the initial step: this is usually creating or configuring a resource. Sub-steps may not be necessary, depending on complexity."
 
-## Before You Begin
+```shell
+# We typically show examples of commands or code in one code block, which can be easily copied by a reader using a button connected to the block.
+```
+```text
+# A second code block is used underneath the first to show what kind of example output to expect from the command. Truncate unnecessary output with ellipses (...).
+```
 
-To complete the instructions in this guide, you need the following:
+### Sub-step 1
 
-1. Provide any prerequisites here.
-2. Format as a numbered or bulleted list as appropriate.
-3. Keep the list entries grammatically parallel.1. Provide any prerequisites here.
+[//]: # "Sub-steps are ways of breaking steps into even smaller sections. Each step or sub-step should focus on one thing at a time: a user should be able to stop at the end of section and come back afterwards without leaving their software in a non-functional state."
 
-## Goal 1 - write as a verb phrase
+---
 
-Add introductory text. Say what the user will be doing.
+### Sub-step 2
 
-To do xzy, take the following steps:
+[//]: # "A useful final sub-step for a given section is some kind of verification or testing, so the reader is confident the steps have been successful."
 
-1. This is where you provide the steps that the user must take to accomplish the goal.
+---
 
-    ```bash
-    code examples should be nested within the list
-    ```
+## Step 2
 
-2. Format as numbered lists.
+[//]: # "Explain any additional steps required. If the how-to guide involves multiple components, each component can have its own step for delineation."
 
-    {{< note >}}Add notes like this.{{</note>}}
+### Sub-step 1
 
-3. If there is only one step, you don't need to format it as a numbered list.
+---
 
-## Goal 2 - write as a verb phrase
+### Sub-step 2
 
-## Goal 3  - write as a verb phrase
+---
 
-## Discussion
+## Step 3
 
-Use the discussion section to expand on the information presented in the steps above.
+[//]: # "The final step of a how-to guide is usually a final test, and summarizes all of the previous steps taken to accomplish the purpose of the guide."
 
-This section contains the "why" information.
+### Sub-step 1
 
-This information lives at the end of the document so that users who just want to follow the steps don't have to scroll through a wall of explanatory text to find them.
+---
 
-## Verification
+### Sub-step 2
 
-Explain how the user can verify the steps completed successfully.
+---
 
-## What's Next
+## See also
 
-- Provide up to 5 links to related topics (optional).
-- Format as a bulleted list.
+[//]: # "Link to related documents, such as concepts, reference material or similar use cases."