|
| 1 | +--- |
| 2 | +# We use sentence case and present imperative tone |
| 3 | +title: "{{ replace .Name "-" " " | title }}" |
| 4 | +# Weights are assigned in increments of 100: determines sorting order |
| 5 | +weight: i00 |
| 6 | +# Creates a table of contents and sidebar, useful for large documents |
| 7 | +toc: false |
| 8 | +# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this |
| 9 | +type: tutorial |
| 10 | +# Intended for internal catalogue and search, case sensitive: |
| 11 | +# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit |
| 12 | +product: |
| 13 | +# Intended for internal catalogue |
| 14 | +docs: "DOCS-000" |
| 15 | +--- |
| 16 | + |
| 17 | +[//]: # "These are Markdown comments to guide you through document structure. Remove them as you go, as well as any unnecessary sections." |
| 18 | +[//]: # "Use underscores for _italics_, and double asterisks for **bold**." |
| 19 | +[//]: # "Backticks are for `monospace`, used sparingly and reserved mostly for executable names - they can cause formatting problems. Avoid them in tables: use italics instead." |
| 20 | + |
| 21 | +[//]: # "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." |
| 22 | + |
| 23 | +This guide is a tutorial on how to set up <thing>. While going through the steps of this tutorial, <concept 1>, <concept 2> and <concept 3> will be introduced and explained to understand how <thing> works. |
| 24 | + |
| 25 | +By the end of the tutorial, you should have enough working knowledge of <thing> to develop your own <configuration/application/etc>. |
| 26 | + |
| 27 | +## Background |
| 28 | + |
| 29 | +[//]: # "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." |
| 30 | +[//]: # "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." |
| 31 | + |
| 32 | +<thing> is a common use for <product>: it enables the ability to use <feature 1>, <feature 2> and <feature 3>, which are important when configuring <product> for <use case>. |
| 33 | + |
| 34 | +--- |
| 35 | + |
| 36 | +## Before you begin |
| 37 | + |
| 38 | +[//]: # "List everything someone will need installed or configured before it's required. Link directly to installation guides where possible." |
| 39 | + |
| 40 | +To complete this guide, you will need the following prerequisites: |
| 41 | + |
| 42 | +- [Requirement 1](some-external-link) |
| 43 | +- [Requirement 2]({{< ref "/some/internal/link.md" >}}) |
| 44 | +- Requirement 3 |
| 45 | + |
| 46 | +[//]: # "Note the style of link for requirement two: keep the markdown extension. Links are resolved from the root of the documentation folder, often /site." |
| 47 | + |
| 48 | +--- |
| 49 | + |
| 50 | +## Step 1 |
| 51 | + |
| 52 | +[//]: # "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." |
| 53 | +[//]: # "If it's a successive step (One after the first), you might refer to work already done to follow the sequence of operations." |
| 54 | + |
| 55 | +The first thing required for setting up <thing> is <step name>. This is the <service/host/etcetera> that the <thing> will run on. The <component> that is set-up from this step is necessary for <requirement>, and will be connected to <other component> and <third component> in a later step. The <thing> we are configuring will look something along the lines of this by the end: |
| 56 | + |
| 57 | +[//]: # "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." |
| 58 | + |
| 59 | +```mermaid |
| 60 | +# You can use Mermaid to draw diagrams in a codeblock with mermaid as the language. |
| 61 | +# Read their documentation for usage: https://mermaid.js.org/intro/ |
| 62 | +``` |
| 63 | + |
| 64 | +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>. |
| 65 | + |
| 66 | +--- |
| 67 | + |
| 68 | +### Sub-step 1 |
| 69 | + |
| 70 | +[//]: # "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." |
| 71 | +[//]: # "Though there may be multiple ways to accomplish a task, focus on showing the reader the exact way to do one." |
| 72 | +[//]: # "You can mention alternative paths, but do not give unnecessary detail: it detracts from the task at hand." |
| 73 | + |
| 74 | +To set up <component>, start by running the following command. It will create <dependency 1>: take note of the <unique identifier> value, as it will be used for connecting <other component> in later steps. |
| 75 | + |
| 76 | +```shell |
| 77 | +# 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. |
| 78 | +``` |
| 79 | +```text |
| 80 | +# 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 (...). |
| 81 | +``` |
| 82 | + |
| 83 | +To verify the creation of <component>, you can also inspect information about it using <command>. The output should look something like this: |
| 84 | + |
| 85 | +```shell |
| 86 | +<a copyable, single line command> |
| 87 | +``` |
| 88 | +``` |
| 89 | +<the output of that command, possibly truncated and with changed IPs or domains> |
| 90 | +``` |
| 91 | + |
| 92 | +--- |
| 93 | + |
| 94 | +### Sub-step 2 |
| 95 | + |
| 96 | +--- |
| 97 | + |
| 98 | +## Step 2 |
| 99 | + |
| 100 | +[//]: # "Explain any additional steps required. If the tutorial involves multiple components, each component can have its own step for delineation." |
| 101 | + |
| 102 | +--- |
| 103 | + |
| 104 | +### Sub-step 1 |
| 105 | + |
| 106 | +--- |
| 107 | + |
| 108 | +### Sub-step 2 |
| 109 | + |
| 110 | +--- |
| 111 | + |
| 112 | +## Conclusion |
| 113 | + |
| 114 | +[//]: # "Summarize everything that the reader will have learned and accomplished by the end of this tutorial." |
| 115 | +[//]: # "It should fulfill the promise made by the introductory paragraph at the top of the document." |
| 116 | +[//]: # "You may wish to link to another tutorial as the next logical step, but that could also be part of the 'See also' section." |
| 117 | + |
| 118 | +--- |
| 119 | + |
| 120 | +## See also |
| 121 | + |
| 122 | +[//]: # "Link to related documents, such as concepts, reference material or similar use cases." |
0 commit comments