Merge pull request #31357 from michelle-purcell/port-doc-contributor-…

…updates

Enhance docs contributor info (2.16.4 backport from main)

docs/src/main/asciidoc/README.adoc

@@ -1,19 +1,20 @@
 = README: Quarkus documentation
 include::_attributes.adoc[]
 
-Quarkus documentation uses asciidoc syntax.
+Quarkus documentation uses link:https://asciidoc.org/[AsciiDoc] markup.
 
-A gradual refactoring effort is underway to reshape Quarkus documentation to make it easier to both read and write (see xref:doc-concept.adoc[Quarkus documentation concepts] for more on this transition).
+A gradual refactoring effort is underway to reshape Quarkus documentation to make it easier to both read and write. For more information about this transition, see xref:doc-concept.adoc[Quarkus documentation content types].
 
 For more information on contributing to Quarkus docs, see:
 
-- xref:doc-contribute-docs-howto.adoc[How to contribute documentation]
-- xref:doc-concept.adoc[Quarkus documentation concepts]
-- xref:doc-reference.adoc[Quarkus documentation reference]
+- xref:doc-contribute-docs-howto.adoc[Contribute to Quarkus documentation]
+- xref:doc-concept.adoc[Quarkus documentation content types]
+- xref:doc-reference.adoc[Quarkus style and content guidelines]
+- xref:doc-create-tutorial.adoc[Creating a tutorial]
 
 == Glossary
 
-This is a collection of preferred term in the documentation and website.
+This is a collection of preferred terms in the documentation and website.
 Please stay within these terms for consistency.
 
 * Live coding:: for our `quarkus:dev` capability

docs/src/main/asciidoc/_templates/template-concept.adoc

@@ -4,7 +4,7 @@ and pull requests should be submitted there:
 https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 ////
 ////
-TODO: See Quarkus documentation reference for details
+TODO: xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines] for details
 - Title should have an implied "Understanding..." in front. 
 - ID should end with '-concept' (using the filename works)
 - choose appropriate categories
@@ -15,8 +15,8 @@ include::_attributes.adoc[]
 :categories: ...
 ////
 :extension-status: preview
-TODO: uncomment the above for for an experimental or tech-preview content. 
-The document header ends at the first blank line.
+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.
 ////
 
 A short introduction that summarizes or frames the concept.
@@ -29,8 +29,8 @@ include::{includes}/extension-status.adoc[]
 
 == Create additional sections
 
-- xref:{doc-guides}/doc-concept.adoc#concept[Documentation concepts: Concept guides]
-- xref:{doc-guides}/doc-reference.adoc[Quarkus documentation reference]
+- xref:{doc-guides}/doc-concept.adoc#concept[Quarkus documentation content types: Concept guides]
+- xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines]
 
 == Guidelines for a good Concept doc
 
@@ -43,7 +43,11 @@ Explanation/Concept documents should do things that the other parts of the docum
 == Language tips:
 
 - Explain: "The reason for x is because historically, y…"
-- Offer judgements and even opinions where appropriate.., "W is better than z, because…"
+- Offer judgments and even opinions where appropriate.., "W is better than z, because…"
 - Provide context that helps the reader: "An x in system y is analogous to a w in system z. However…"
 - Weigh up alternatives: "Some users prefer w (because z). This can be a good approach, but…"
-- Unfold the machinery’s internal secrets, to help understand why something does what it does: "An x interacts with a y as follows:…"
+- Unfold the machinery’s internal secrets, to help understand why something does what it does: "An x interacts with a y as follows:…"
+
+== 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.

docs/src/main/asciidoc/_templates/template-howto.adoc

@@ -4,7 +4,7 @@ and pull requests should be submitted there:
 https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 ////
 ////
-TODO: See Quarkus documentation reference for details
+TODO: See xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines] for details
 - Title should have an implied "How to..." in front. 
 - ID should end with '-howto' (using the filename works)
 - choose appropriate categories
@@ -15,11 +15,11 @@ include::_attributes.adoc[]
 :categories: ...
 ////
 :extension-status: preview
-TODO: uncomment the above for for an experimental or tech-preview content. 
-The document header ends at the first blank line.
+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.
 ////
 
-How-to guides are goal-oriented, and should help the reader accomplish a task (where there may be forks in the path).
+How-to guides are goal-oriented and should help the reader accomplish a task (where there may be forks in the path).
 
 ////
 TODO: If this is a reference for an experimental or tech-preview extension, uncomment the following (otherwise delete)
@@ -33,16 +33,20 @@ Your user will also be in the middle of something: define the starting-point tha
 == Resources
 
 - xref:{doc-guides}/doc-create-howto-tutorial.adoc[Tutorial: Create a How-To]
-- xref:{doc-guides}/doc-concept.adoc#howto-guide[Documentation concepts: How-to guides]
-- xref:{doc-guides}/doc-reference.adoc[Quarkus documentation reference]
+- xref:{doc-guides}/doc-concept.adoc#howto-guide[Quarkus documentation content types: How-to guides]
+- xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines]
 
 == Guidelines for good How-To guides
 
-- 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.
+- 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.
 
 == Examples
 
 Baeldung tutorials provide solid examples of How-To guides.
-For example, "How to use Jackson annotations" is answered (with variations) here: https://www.baeldung.com/jackson-annotations
+For example, "How to use Jackson annotations" is answered (with variations) here: https://www.baeldung.com/jackson-annotations
+
+== 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.

docs/src/main/asciidoc/_templates/template-reference.adoc

@@ -4,7 +4,7 @@ and pull requests should be submitted there:
 https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 ////
 ////
-TODO: See Quarkus documentation reference for details
+TODO: See xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines] for details
 - Title should have an implied "About..." in front. 
 - ID should end with '-reference' (using the filename works)
 - choose appropriate categories
@@ -15,8 +15,8 @@ include::_attributes.adoc[]
 :categories: ...
 ////
 :extension-status: preview
-TODO: uncomment the above for for an experimental or tech-preview content. 
-The document header ends at the first blank line.
+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.
 ////
 
 A short introduction that describes the content of this reference.
@@ -29,8 +29,8 @@ include::{includes}/extension-status.adoc[]
 
 == Add additional sections
 
-- xref:{doc-guides}/doc-concept.adoc#reference[Documentation concepts: Reference guides]
-- xref:{doc-guides}/doc-reference.adoc[Quarkus documentation reference]
+- xref:{doc-guides}/doc-concept.adoc#reference[Quarkus documentation content types: Reference guides]
+- xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines]
 
 == Guidelines for a good reference
 
@@ -52,4 +52,8 @@ TODO: If this is an extension reference, include the relevant configuration
 == Configuration Reference
 
 include::{generated-dir}/config/<<generated-filename>>.adoc[opts=optional, leveloffset=+1]
-////
+////
+
+== 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.

docs/src/main/asciidoc/_templates/template-tutorial.adoc

@@ -4,7 +4,7 @@ and pull requests should be submitted there:
 https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 ////
 ////
-TODO: See Quarkus documentation reference for details
+TODO: See xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines]for details
 - Finish a sentence like: "Create a ...", "How to ..." 
 - ID should end with '-tutorial' (using the filename works)
 - choose appropriate categories 
@@ -15,8 +15,8 @@ include::_attributes.adoc[]
 :categories: ...
 ////
 :extension-status: preview
-TODO: uncomment the above for for an experimental or tech-preview content. 
-The document header ends at the first blank line.
+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.
 ////
 
 Describe what the learner will accomplish (examples: build, create, construct, deploy; not: “you will learn...”).
@@ -43,8 +43,8 @@ This file offers a few different variables that can be used to tweak what is sho
 == Outline steps
 
 - xref:{doc-guides}/doc-create-tutorial.adoc[Tutorial: Create a tutorial]
-- xref:{doc-guides}/doc-concept.adoc#tutorial[Documentation concepts: Tutorials]
-- xref:{doc-guides}/doc-reference.adoc[Quarkus documentation reference]
+- xref:{doc-guides}/doc-concept.adoc#tutorial[Quarkus documentation content types: Tutorials]
+- xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines]
 
 Each step should conclude with a comprehensible/observable result.
 
@@ -61,3 +61,7 @@ Link to more detailed explanation.
 == Summary
 
 In closing, describe (and admire, in a mild way) what your learner has accomplished (not: “you have learned…”).
+
+== 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.

docs/src/main/asciidoc/doc-concept.adoc

@@ -4,20 +4,27 @@ and pull requests should be submitted there:
 https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 ////
 [id="doc-concept"]
-= Quarkus documentation concepts
+= Quarkus documentation content types
 include::_attributes.adoc[]
 :categories: contributing
 :fn-diataxis: footnote:diataxis[Procida, D. Diátaxis documentation framework. https://diataxis.fr/]
 
-Overview of concepts underlying the structure and composition of Quarkus docs.
+Quarkus documentation is structured into four distinct content types: concepts, how-tos, tutorials, and references.
+The composition and structure of Quarkus docs follow the Diátaxis systematic documentation framework for technical documentation authoring.
+Each content type resolves a different user need, fulfills a different purpose, and requires a different approach to its creation.
 
-== Content Types
+== Diátaxis documentation framework
+
+We chose to align Quarkus docs with the Diátaxis documentation framework{fn-diataxis}, which defines a core content structure that addresses the different needs users have when consulting docs. 
+
+image::diataxis-framework.png[The content types in the Diátaxis documentation framework{fn-diataxis},width=40%, align=left]
+
+*Image credit: https://diataxis.fr/*
 
-We are aligning Quarkus docs with the Diátaxis documentation framework{fn-diataxis}, which defines a core content structure that addresses the different needs users have when consulting docs. 
 What follows is a brief summary of the different document types, but their site is worth a read if you want to understand more of the reasoning behind this classification.
 
 [[concept]]
-=== Concept guides (Explanation)
+== Concept guides (Explanation)
 
 > Explanation is _discussion_ that clarifies and illuminates a particular topic. Explanation is _understanding-oriented_.
 
@@ -34,7 +41,7 @@ You can cite design decisions, historical reasons, and technical constraints to
 - may express opinions about advantages and drawbacks of the concept that you are explaining relative to different potential use cases or applications.
 
 [[howto-guide]]
-=== How-To guides
+== How-to guides
 
 > How-to guides are _directions_ that take the reader through the steps required to solve a real-world problem. How-to guides are _goal-oriented_.
 
@@ -49,7 +56,7 @@ Good how-to guides:
 - are practical (rather than complete).
 
 [[reference]]
-=== Reference guides
+== Reference guides
 
 > Reference guides are _technical descriptions_ of the machinery and how to operate it. Reference material is _information-oriented_.
 
@@ -66,7 +73,7 @@ Good reference guides:
 
 
 [[tutorial]]
-=== Tutorials
+== Tutorials
 
 > Tutorials are _lessons_ that take the reader by the hand through a series of steps to complete a project of some kind. Tutorials are _learning-oriented_.
 
@@ -78,8 +85,5 @@ Good tutorials:
 - are reliable and consistent (they work for all users, every time).
 - include only enough information to complete the task. 
   They delegate to other documentation types (concepts or reference) to provide additional context.
-- focus on one way of doing the task. Alternative approaches are explored in other document types
-  (a how-to guide, for example).
-
-
-
+- focus on one way of doing the task. 
+Alternative approaches are explored in other document types (a how-to guide, for example).