Merge pull request #31127 from michelle-purcell/doc-contributor-guide-enhancements

Enhancements to instructions for contributing to the Quarkus docs

Author: ebullient

docs/src/main/asciidoc/doc-contribute-docs-howto.adoc

@@ -54,6 +54,18 @@ include::_attributes.adoc[] <3>
 <2> For information about how to create a good title for each content type, see xref:{doc-guides}/doc-reference.adoc#titles-and-headings[Titles and headings] on the "Quarkus style and content guidelines" page.
 <3> The `_attributes.adoc` include is required to ensure that attributes get resolved, the table of contents is generated, and content renders in the website portal. 
 <4> Set at least one category to ensure that the content is findable on the link:https://quarkus.io/guides/[Quarkus documentation home page]. For a list of Quarkus categories, see xref:{doc-guides}/doc-reference.adoc#document-attributes-and-variables[Document attributes and variables] on the "Quarkus style and content guidelines" page.
++
+[IMPORTANT]
+====
+Ensure there are no line breaks in the header section until after `:categories:` line.
+====
++
+. Add an abstract to describe the purpose of the guide.
+[IMPORTANT]
+====
+The first sentence of the abstract must explain the value and some benefit of the content in less than 27 words because this automatically displays on the link:https://quarkus.io/guides/[Quarkus guides homepage]. 
+There must also be a line break before and after the abstract.
+====
 
 For more information about the minimum header requirements, see xref:{doc-guides}/doc-reference.adoc#document-structure[Document structure] on the "Quarkus style and content guidelines" page.
 
@@ -75,8 +87,8 @@ newUrl: /guides/<new_asciidoc_filename> // <2>
 ---
 +
 Where:
-<1> Is the name of the original AsciiDoc source file that you are retiring.
-<2> Is the name of the AsciiDoc source file that you want to redirect to.
+<1> Is the name of the original AsciiDoc source file that you are retiring, without the `.adoc` file extension.
+<2> Is the name of the AsciiDoc source file that you want to redirect to, without the `.adoc` file extension.
 
 .Example
 

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

@@ -149,29 +149,40 @@ Minimally, each document should define and id and a title, and include common at
 <3> Include common document attributes.
 <4> Specify the relevant <<Categories>> (comma separated).
 
-==== Other common document attributes:
+[[doc-header-optional]]
+==== Other common document header attributes
 
 `:extension-status: preview`:: Use this attribute to flag special types of content. Valid values: `experimental`, `preview`, `stable` (not usually used), and `deprecated`.
 `:summary: <text>`:: Use the summary to provide a concise (26 words or less) description of the document. 
-This attribute will be used in tiles or other descriptions on the website. If not present, the contents of the <<Abstracts (preamble),preamble>> will be used instead.
+The value of this attribute is used in tiles or other descriptions on the website and is not required in newer diataxis-styled docs, as outlined in <<abstracts-preamble>>. 
+If not present, the first sentence of the abstract is automatically used to generate the tile summary. 
 
-NOTE: Take care with whitespace when working with document-scoped attributes. The document header ends with the first blank line. 
+IMPORTANT: Take care with whitespace when working with document-scoped attributes. The document header ends with the first blank line. 
 
+[[abstracts-preamble]]
 === Abstracts (preamble)
 
-Add a short description that helps your audience to quickly find and understand the purpose and intent of the page.
+The first paragraph in the main body is treated as the abstract, also referred to as the preamble.
+Add a short description that helps your audience quickly find and understand the purpose and intent of the page.
+The first sentence of the abstract provides a summary and gets automatically added to the tile on the link:https://quarkus.io/guides/[Quarkus guides homepage].
 
 Try to write the abstract by using the following guidelines:
 
 * *User oriented:* Contains terms and keywords that are familiar to users.
-* *Concise:* Avoids self-referential expressions and filler words, for example, "This document..", "This tutorial..", or "The following.."
+* *Concise:* Avoids self-referential expressions and filler words, for example:
+** "This document.."
+** "This tutorial..."
+** "The following..."
 * *Brief:* Is no more than three sentences long. 
 
 [IMPORTANT]
 ====
-The first sentence of the abstract must explain the value and some benefit of the content in less than 27 words because this automatically displays on the link:https://quarkus.io/guides/[Quarkus guides homepage].
+Ensure that the first sentence explains the value and some benefits of the content in 26 words or less.
 ====
 
+If the first sentence is too long or can not be simplified to fit on the website tile, you can define a ``:summary:`` attribute in the document header attributes to serve that purpose. 
+For more information, see <<doc-header-optional>>.
+
 === Semantic line breaks
 
 :semantic-line-breaks: footnote:smbl[Rhodes, B. Semantic Linefeeds. https://rhodesmill.org/brandon/2012/one-sentence-per-line/]