From 1b080934f5c99b1e136dc6185865865c49f21b31 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Wed, 7 May 2025 12:46:38 +0100 Subject: [PATCH] feat: Update Hugo archetypes to remove HRs and change final subsection This commit updates the Hugo archetypes to remove the horizontal lines delineating each section, and also changes the final sections of each section. The future website theme uses meaningful whitespace for breaking sections up instead of horizontal lines, so removing it from the templates prevents more from being added. "See also" was changed to "Next steps" for two of the archetypes, with more specific examples for all three. This reflects discussions around the fact that "See also" doesn't inspire informed content design. "Next steps" is more appropriate for specific use cases, especially with the context of the working document - we have a good idea of what the reader may need to do next, so the title should reflect that. --- archetypes/concept.md | 9 +-------- archetypes/default.md | 17 ++--------------- archetypes/tutorial.md | 19 ++----------------- 3 files changed, 5 insertions(+), 40 deletions(-) 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."