From 3689bdd5c0c57e3a554357473522ae53f2b81b07 Mon Sep 17 00:00:00 2001 From: Michelle Purcell Date: Thu, 26 Jan 2023 16:39:57 +0000 Subject: [PATCH] Enhancements to the doc contributor guide for adding abstracts and redirection to diataxis styled topics Added clarification about the abstract/preamble. Edits Added native to doc categories Removed native entry. This overlaps with another PR --- .../main/asciidoc/doc-contribute-docs-howto.adoc | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc b/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc index 363274ea3fb46c..3880fd7337a984 100644 --- a/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc +++ b/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/ // <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