From d8ef18f61f78225b8cb1ccdbf5440f1d2189e4db Mon Sep 17 00:00:00 2001 From: Rolfe Dlugy-Hegwer Date: Tue, 16 May 2023 13:54:39 -0400 Subject: [PATCH] Added prereqs to the how to template --- .../asciidoc/_templates/template-howto.adoc | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/docs/src/main/asciidoc/_templates/template-howto.adoc b/docs/src/main/asciidoc/_templates/template-howto.adoc index d0ebb6ccccb50e..3f69753b6bdd51 100644 --- a/docs/src/main/asciidoc/_templates/template-howto.adoc +++ b/docs/src/main/asciidoc/_templates/template-howto.adoc @@ -5,7 +5,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// //// TODO: See xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines] for details -- Title should have an implied "How to..." in front. +- Title should have an implied "How to..." in front. - ID should end with '-howto' (using the filename works) - choose appropriate categories //// @@ -15,7 +15,7 @@ include::_attributes.adoc[] :categories: ... //// :extension-status: preview -TODO: uncomment the above for experimental or tech-preview content. +TODO: uncomment the above for experimental or tech-preview content. The document header ends at the first blank line. Do not remove the blank line between the header and the abstract summary. //// @@ -26,6 +26,17 @@ TODO: If this is a reference for an experimental or tech-preview extension, unco include::{includes}/extension-status.adoc[] //// +== Prerequisites + +//// +TODO: If this tutorial will use dev tools, use the following common include: +include::{includes}/devtools/prerequisites.adoc[] +This file offers a few different variables that can be used to tweak what is shown. +//// + +- Materials, software, ... +- Whatever they should already have in hand to complete this set of steps + == Define the problem Your user will also be in the middle of something: define the starting-point that they know how to reach and a conclusion that answers a real question. @@ -49,6 +60,8 @@ To create anchors for in-file and cross-file navigation, see the following detai - Don’t explain concepts; link to a related concept/explainer. - Be flexible; a how-to guide needs to be adaptable to real-world use cases. - Omit the unnecessary; practical usability is more helpful than completeness. +- A how-to guide can include multiple tasks, each with its own H2 heading. +- For suggestions on how to write a good how-to guide, see https://diataxis.fr/how-to-guides/#writing-a-good-how-to-guide. == Examples @@ -57,4 +70,4 @@ For example, "How to use Jackson annotations" is answered (with variations) here == References -To help direct the reader to more information about the content topic, optionally add a *References* section to the end of the page and include `links` or `xrefs` to other related content resources. \ No newline at end of file +To help direct the reader to more information about the content topic, optionally add a *References* section to the end of the page and include `links` or `xrefs` to other related content resources.