From f6357656d6864ec9ed491f85f804641844e06e48 Mon Sep 17 00:00:00 2001 From: Michelle Purcell Date: Mon, 15 Aug 2022 14:15:25 +0100 Subject: [PATCH 1/2] Add guidance for creating a Quarkus doc abstract --- docs/src/main/asciidoc/doc-reference.adoc | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/src/main/asciidoc/doc-reference.adoc b/docs/src/main/asciidoc/doc-reference.adoc index 42f12a3739e5f..6e06989916639 100644 --- a/docs/src/main/asciidoc/doc-reference.adoc +++ b/docs/src/main/asciidoc/doc-reference.adoc @@ -82,8 +82,16 @@ The following links provide background on Asciidoc syntax and general convention :semantic-line-breaks: footnote:smbl[Rhodes, B. Semantic Linefeeds. https://rhodesmill.org/brandon/2012/one-sentence-per-line/] Text in paragraphs, lists, and tables should be broken into pieces that are easier to review{semantic-line-breaks}. -Start a new line at the end of each sentence, and -split sentences themselves at natural breaks between clauses. +Start a new line at the end of each sentence, and split sentences themselves at natural breaks between clauses. + +=== Abstracts (preamble) + +For optimum findability, add a short description using user-oriented keywords to summarize the document's purpose, task, and intent in no more than three sentences. + +[IMPORTANT] +==== +The first sentence of the abstract must explain the value and some benefit of the content in less than 26 words because this automatically displays on the link:https://quarkus.io/guides/[Quarkus guides homepage]. +==== === Automatic Table of Contents (TOC) From 1d86ed28ff3c78374b3b9d2aa2d397fe89325b22 Mon Sep 17 00:00:00 2001 From: Michelle Purcell Date: Mon, 15 Aug 2022 14:30:03 +0100 Subject: [PATCH 2/2] Fixed example tutorial abstract to match guidance --- docs/src/main/asciidoc/doc-create-tutorial.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/src/main/asciidoc/doc-create-tutorial.adoc b/docs/src/main/asciidoc/doc-create-tutorial.adoc index d85db0c3d59f6..8004519d0795c 100644 --- a/docs/src/main/asciidoc/doc-create-tutorial.adoc +++ b/docs/src/main/asciidoc/doc-create-tutorial.adoc @@ -62,9 +62,9 @@ They should be able to determine if they want to engage with the content. [source,asciidoc] ---- -In this tutorial, we will create an application that uses unique annotations from the experimental acme extension to define two endpoints: -a simple Http endpoint and an endpoint that emits Server-Sent Events (SSE). -We will also use Quarkus dev mode for iterative development and test. +Create an application that uses unique annotations from the experimental acme extension to define two endpoints: +a simple HTTP endpoint and an endpoint that emits server-sent events (SSE). +We will also use Quarkus dev mode for iterative development and testing. ---- .Document Preview