From 91f1c4a5832bed270222ab7bba8e13b63c64d9b9 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 --- .../main/asciidoc/doc-contribute-docs-howto.adoc | 16 ++++++++++++++-- docs/src/main/asciidoc/doc-reference.adoc | 1 + 2 files changed, 15 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 diff --git a/docs/src/main/asciidoc/doc-reference.adoc b/docs/src/main/asciidoc/doc-reference.adoc index a5e76989ca3ec2..c644fb09bf84e1 100644 --- a/docs/src/main/asciidoc/doc-reference.adoc +++ b/docs/src/main/asciidoc/doc-reference.adoc @@ -329,6 +329,7 @@ Quarkus documentation is grouped into the following categories. | integration | Support for integration extensions (Camel) | messaging | Integrations with messaging systems like Kafka, AMQP, or RabbitMQ. | miscellaneous | Miscellaneous +native | observability | Extensions and integrations for runtime and application observability | reactive | Extensions that support reactive technologies and techniques | security | Security