diff --git a/archetypes/concept.md b/archetypes/concept.md deleted file mode 100644 index c40526fa..00000000 --- a/archetypes/concept.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -# We use sentence case and present imperative tone -title: "{{ replace .Name "-" " " | title }}" -# 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" ---- - -[//]: # "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 provides an overview of , which is used , and . - -It is an example of a , and is closely related to . - ---- - -## 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." - -```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 of the diagram, you can see that is connected to : this relationship is established when configuring as part of . - -[//]: # "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." - ---- - -## See also - -[//]: # "Link to related documents, such as concepts, reference material or similar use cases." \ No newline at end of file diff --git a/archetypes/default.md b/archetypes/default.md deleted file mode 100644 index 6797a233..00000000 --- a/archetypes/default.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -# We use sentence case and present imperative tone -title: "{{ replace .Name "-" " " | title }}" -# 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" ---- - -[//]: # "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 with . In involves the use of , and , demonstrating how works with an example . - ---- - -## 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." - ---- - -## Step 1 - -[//]: # "Explain the initial step: this is usually creating or configuring a resource. Sub-steps may not be necessary, depending on complexity." - -```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 (...). -``` - -### Sub-step 1 - -[//]: # "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." - ---- - -### Sub-step 2 - -[//]: # "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." - ---- - -## Step 2 - -[//]: # "Explain any additional steps required. If the how-to guide involves multiple components, each component can have its own step for delineation." - -### Sub-step 1 - ---- - -### Sub-step 2 - ---- - -## Step 3 - -[//]: # "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." - -### Sub-step 1 - ---- - -### Sub-step 2 - ---- - -## See also - -[//]: # "Link to related documents, such as concepts, reference material or similar use cases." \ No newline at end of file diff --git a/archetypes/tutorial.md b/archetypes/tutorial.md deleted file mode 100644 index eb16ada8..00000000 --- a/archetypes/tutorial.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -# We use sentence case and present imperative tone -title: "{{ replace .Name "-" " " | title }}" -# 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: tutorial -# 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" ---- - -[//]: # "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 is a tutorial on how to set up . While going through the steps of this tutorial, , and will be introduced and explained to understand how works. - -By the end of the tutorial, you should have enough working knowledge of to develop your own . - -## Background - -[//]: # "The largest difference between a tutorial and a how-to document is the scope of detail included. While working on the tutorial, consider what overlap might exist with a concept document." -[//]: # "We want to reduce the amount of context switching a reader has to go through, so it might be beneficial to convert some text content into an include for re-use between a tutorial and a concept document." - - is a common use for : it enables the ability to use , and , which are important when configuring for . - ---- - -## 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." - ---- - -## Step 1 - -[//]: # "The text immediately following a heading in a tutorial should likely explain a concept to build a mental model of what the reader is about to do." -[//]: # "If it's a successive step (One after the first), you might refer to work already done to follow the sequence of operations." - -The first thing required for setting up is . This is the that the will run on. The that is set-up from this step is necessary for , and will be connected to and in a later step. The we are configuring will look something along the lines of this by the end: - -[//]: # "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." - -```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 of the diagram, you can see that is connected to : this relationship is established when configuring as part of . - ---- - -### Sub-step 1 - -[//]: # "The sub-steps of a tutorial should show the exact steps a reader should take to accomplish an action, and what to expect when doing so." -[//]: # "Though there may be multiple ways to accomplish a task, focus on showing the reader the exact way to do one." -[//]: # "You can mention alternative paths, but do not give unnecessary detail: it detracts from the task at hand." - -To set up , start by running the following command. It will create : take note of the value, as it will be used for connecting in later steps. - -```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 verify the creation of , you can also inspect information about it using . The output should look something like this: - -```shell - -``` -``` - -``` - ---- - -### Sub-step 2 - ---- - -## Step 2 - -[//]: # "Explain any additional steps required. If the tutorial involves multiple components, each component can have its own step for delineation." - ---- - -### Sub-step 1 - ---- - -### Sub-step 2 - ---- - -## Conclusion - -[//]: # "Summarize everything that the reader will have learned and accomplished by the end of this tutorial." -[//]: # "It should fulfill the promise made by the introductory paragraph at the top of the document." -[//]: # "You may wish to link to another tutorial as the next logical step, but that could also be part of the 'See also' section." - ---- - -## See also - -[//]: # "Link to related documents, such as concepts, reference material or similar use cases." \ No newline at end of file