diff --git a/archetypes/concept.md b/archetypes/concept.md index 6543c698e..b72f32b60 100644 --- a/archetypes/concept.md +++ b/archetypes/concept.md @@ -22,15 +22,11 @@ This guide provides an overview of , which is used , 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'" @@ -56,7 +52,6 @@ Starting from the of the diagram, you can see that is connect ### Use case 2 ---- ## Conclusion @@ -65,8 +60,6 @@ Starting from the of the diagram, you can see that is connect [//]: # "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." +[//]: # "Link to related documents, such as reference material or task instructions." diff --git a/archetypes/default.md b/archetypes/default.md index f6bc3566e..ba9cf1281 100644 --- a/archetypes/default.md +++ b/archetypes/default.md @@ -20,8 +20,6 @@ nd-product: 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." @@ -34,8 +32,6 @@ To complete this guide, you will need the following prerequisites: [//]: # "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." @@ -51,25 +47,19 @@ To complete this guide, you will need the following prerequisites: [//]: # "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 @@ -77,12 +67,9 @@ To complete this guide, you will need the following prerequisites: ### Sub-step 1 ---- ### Sub-step 2 ---- - -## See also +## Next steps -[//]: # "Link to related documents, such as concepts, reference material or similar use cases." +[//]: # "Link to the most common use cases after this specific instruction. For example. configuration usually follows installation." diff --git a/archetypes/tutorial.md b/archetypes/tutorial.md index 5efa9e260..1190e6072 100644 --- a/archetypes/tutorial.md +++ b/archetypes/tutorial.md @@ -29,8 +29,6 @@ By the end of the tutorial, you should have enough working knowledge of 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." @@ -43,8 +41,6 @@ To complete this guide, you will need the following prerequisites: [//]: # "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." @@ -61,8 +57,6 @@ The first thing required for setting up is . This is 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." @@ -87,25 +81,17 @@ To verify the creation of , you can also inspect information about it ``` ---- - ### 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 @@ -113,8 +99,7 @@ To verify the creation of , you can also inspect information about it [//]: # "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 +## Next steps -[//]: # "Link to related documents, such as concepts, reference material or similar use cases." +[//]: # "Link to related documents, such as concepts, reference material or specific use cases."