Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Added guidance for diataxis templates & xrefs
Browse files Browse the repository at this point in the history
Fix one sentence per line

Fix issues with sections

Fix structure
michelle-purcell committed Jun 12, 2023
1 parent bbd08cb commit 0f5130c
Showing 2 changed files with 97 additions and 41 deletions.
18 changes: 10 additions & 8 deletions docs/src/main/asciidoc/doc-contribute-docs-howto.adoc
Original file line number Diff line number Diff line change
@@ -8,21 +8,23 @@ include::_attributes.adoc[]
:categories: contributing
:fn-diataxis: footnote:diataxis[Procida, D. Diátaxis documentation framework. https://diataxis.fr/]

Contribute to the documentation by using the recommended steps, workflow, and style guidance to ensure the content successfully renders on the Quarkus website portal.

== Prerequisites
Contribute to the documentation by using the recommended diataxis content types, steps, workflow, and style guidance to ensure the content successfully renders on the Quarkus website portal.

Quarkus docs use link:https://asciidoc.org/[AsciiDoc] markup.

We suggest you have the following materials nearby:
== Prerequisites

- An editor or IDE that provides syntax highlighting and previews for AsciiDoc, either natively or with a plugin.
- The https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc syntax reference]
- The xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines] for the required syntax, preferred style, and other conventions.
* You have an editor or IDE that provides syntax highlighting and previews for AsciiDoc, either natively or with a plugin.
* You have reviewed the following Quarkus contributor resources:
** The link:https://github.com/quarkusio/quarkus/blob/main/CONTRIBUTING.md#documentation[Documentation] section of the Quarkus "Contributing" guide.
** The xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines] for the required syntax, preferred style, and other conventions.
** The xref:{doc-guides}/doc-concept.adoc[Quarkus documentation content types].
* You have the https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc syntax reference] nearby.

== Locate the source files for Quarkus docs

- AsciiDoc files are in the `src/main/asciidoc` directory within the `docs` module of the {quarkus-base-url}/tree/main/docs[Quarkus GitHub repository].
- The Quarkus doc templates are located in the `src/main/asciidoc/_templates` directory within the `docs` module of the {quarkus-base-url}/tree/main/docs[Quarkus GitHub repository].
- Configuration documentation is generated from JavaDoc comments in Java source files.
- Java, YAML, and other source files can also be xref:doc-reference.adoc#reference-source-code[referenced] by AsciiDoc files.
- The link:https://quarkus.io/guides/[Quarkus documentation] menu page, also known as the doc index page, is sourced in the link:https://github.com/quarkusio/quarkusio.github.io[quarkusio.github.io] repository.
@@ -209,7 +211,7 @@ xref:<other-file-name>.adoc#title-heading[Title heading]

Breaking this example apart, we are using the `xref` macro to refer to another file (`xref:<name-of-the-file>.adoc[Human-readable label]`) and inserting the anchor ID for the target section (`#title-heading`) just after the file name.

See the xref:doc-reference.adoc#cross-references[Cross-references] section for path attributes that should be used in cross-document references.
For more guidelines on writing cross-references, including the recommended path attributes, see xref:doc-reference.adoc#cross-references[Cross-references].

== Preview and build Quarkus documentation

120 changes: 87 additions & 33 deletions docs/src/main/asciidoc/doc-reference.adoc
Original file line number Diff line number Diff line change
@@ -8,8 +8,21 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
include::_attributes.adoc[]
:categories: contributing

Guidelines are provided to help you to contribute clear and consistent content that is also sourced in the required structure and composition of Quarkus documentation.
Guidelines are provided to help you to contribute clear and consistent content that is also sourced in the required diataxis structure and composition of Quarkus documentation.

[[content-types]]
== Quarkus content types

Quarkus documentation is structured into four distinct xref:doc-concept.adoc[content types]: concepts, how-tos, tutorials, and references.
The composition and structure of Quarkus docs follow the link:https://diataxis.fr/[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.

Quarkus provides a set of templates in the link:https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc/_templates[`docs/src/main/asciidoc/_templates`] subdirectory to help you to contribute and create consistent quality content.

Before creating a large guide, design your content by using one of the Quarkus doc templates and using the xref:doc-contribute-howto.adoc[Contribute to Quarkus documentation] how-to guide.


[[asciidoc-syntax]]
== AsciiDoc syntax

Quarkus docs use AsciiDoc syntax.
@@ -19,22 +32,28 @@ The following links provide background on AsciiDoc syntax and general convention
* https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoctor User Manual]
* https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc Syntax Quick Reference]


[[lang-grammar]]
== Language and grammar

Write clear, concise, and consistent technical information in US English.
Write for a global audience with localization, translation, inclusivity, and diversity in mind.
Write clear, concise, and consistent technical information in US English.
Write for a global audience with localization, translation, inclusivity, and diversity in mind.
Try to use the following grammar styles:

* link:https://developers.google.com/style/tense?hl=en[Present tense]
* link:https://developers.google.com/style/voice?hl=en[Active voice]
* link:https://developers.google.com/style/voice?hl=en[Active voice]
* link:https://developers.google.com/style/person?hl=en[Second person (you)]
* link:https://developers.google.com/style/tone?hl=en[A conversational tone]
* link:https://developers.google.com/style/pronouns?hl=en[Gender neutral language]


[[sentence-length]]
== Sentence length

Shorter sentences are much easier to read and translate. Try to use less than 32 words per sentence.


[[website-publish]]
== Website publication

Content from this repository is published to the https://quarkus.io/guides/[Quarkus.io website].
@@ -85,11 +104,13 @@ Your titles and headings must also follow the specific guidance for the Quarkus
* State what task the user will complete, with emphasis on the key topic or demonstrated activity
* Be action-oriented or task-oriented, rather than feature-oriented
* Be led by the needs of the user in learning mode.
* Finish the implied sentence: "In this tutorial, you will ..."
* Finish the implied sentence: "In this tutorial, you will ..."
|Create a Quarkus application in JVM mode by using the quick start example
|Creating an App
|===


[[file-conventions]]
== File conventions

=== Source locations
@@ -107,7 +128,7 @@ AsciiDoc output to HTML:: AsciiDoc processing creates HTML files in `docs/target

=== Templates

Create new documentation files with the appropriate template for the content type:
Create new documentation files with the appropriate template for the content type:

Concepts:: Use `docs/src/main/asciidoc/_templates/template-concept.adoc`
How-To Guides:: Use `docs/src/main/asciidoc/_templates/template-howto.adoc`
@@ -131,12 +152,16 @@ Suffix:: The file name should reflect the document type:
- References should end in `-reference.adoc`
- Tutorials should end in `-tutorial.adoc`


[[doc-structure]]
== Document structure

Use the Quarkus templates to ensure that your content is consistent with the preferred Quarkus documentation structure and style.

[[document-header]]
=== Document header

Each document should define a header for document-scoped attributes.
Each document should define a header for document-scoped attributes.
Minimally, each document should define and id and a title, and include common attributes (`_attributes.adoc`).

[source,asciidoc]
@@ -156,9 +181,9 @@ Minimally, each document should define and id and a title, and include common at
==== 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.
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.
`:summary: <text>`:: Use the summary to provide a concise (26 words or less) description of the document.
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.

IMPORTANT: Take care with whitespace when working with document-scoped attributes.
The document header ends with the first blank line.
@@ -177,14 +202,14 @@ Try to write the abstract by using the following guidelines:
** "This document.."
** "This tutorial..."
** "The following..."
* *Brief:* Is no more than three sentences long.
* *Brief:* Is no more than three sentences long.

[IMPORTANT]
====
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.
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
@@ -194,14 +219,13 @@ For more information, see <<doc-header-optional>>.
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.

=== Using sections
=== Sections

Section titles should be written in sentence case rather than title case.

All documents should start with a Title (a `= Level 0` heading), and should
be broken into subsections where appropriate
(`== Level 1` to `====== Level 5`)
without skipping any levels.
Start your document with a title, which in AsciiDoc is defined as a `= Level 0` heading.
Where appropriate, divide your content into subsections, which in AsciiDoc are defined as `== Level 1` to `====== Level 5`.
Do not skip any levels.

[TIP]
====
@@ -216,7 +240,7 @@ For example, if this is a reference, should some of this content be moved to a c
See xref:{doc-guides}/doc-concept.adoc[Quarkus documentation content types] for more information about content types and organization.
====

=== Links
== Links

In general, prefer link:https://docs.asciidoctor.org/asciidoc/latest/macros/url-macro/[url macros] to bare or automatic links.
Provide human-readable text for the link, especially if it is included in the middle of other text.
@@ -235,9 +259,13 @@ The above source produces this link:https://docs.asciidoctor.org/asciidoc/latest
=====

[[cross-references]]
=== Cross-references
== Cross-references

Quarkus documentation is built from source in a few different environments.

[[xref-source-attributes]]
=== Cross-reference source attributes

We use attributes in our cross-references to ensure our docs can be built across these environments.

.Cross-reference source attributes
@@ -262,7 +290,7 @@ xref:{doc-guides}/doc-concept.adoc[Quarkus Documentation concepts] <1>
<1> The cross-reference starts with `xref:`, uses a cross-reference source attribute(`\{doc-guides}`), and provides a readable description: `[Quarkus Documentation concepts]`.

[[anchors-reference]]
==== Anchors for in-file and cross-file navigation
=== Anchors for in-file and cross-file navigation

* To create an anchored ID, use lower-case characters, separate each word with `-`, and enclose the ID in `[[]]` as in the example below.
+
@@ -303,11 +331,36 @@ xref:<other-file-name>.adoc#title-heading[Title heading]
----
xref:<name-of-the-file>.adoc[Human-readable label]
----
For more details about anchored IDs, see the xref:doc-contribute-docs-howto.adoc#anchors-howto[Cross-reference in-file and cross-file content by using anchors] section.
For more details about anchored IDs, see the xref:doc-contribute-docs-howto.adoc#anchors-howto[Cross-reference in-file and cross-file content by using anchors] section of the "Contribute to Quarkus documentation" guide.

[[cross-reference-phrasing]]
=== Cross-reference phrasing

For consistency and context clarity, use the following guidelines for constructing your cross-reference phrases:

=== Reference source code
* Provide a direct hyperlink to the section, using the `xref` guidance in the previous section.
* Specify the full title of the section and use sentence case.
* Add the definite article “the” before the section title and specify “section” directly after the title.
* Add the definite article “the” and “Quarkus” before the title of the guide, unless the word “Quarkus" is already in the title.
* Insert the title of the guide between double quotations and specify “guide” directly after the title.
* If the context is needed, lead with the phrase:
** "For more information about ..."

There are many ways to include source code and examples in documentation.
.Correct and incorrect cross-reference phrases
[options="header"]
|====
|Correct|Incorrect
|For more information, see the xref:validation.adoc#configuring-the-validatorfactory[Configuring the ValidatorFactory] section of the Quarkus "Validation with Hibernate Validator" guide.|For more information, see the 'Configuring the ValidatorFactory' section of the xref:validation.adoc[VALIDATION WITH HIBERNATE VALIDATOR guide].
|For more information, see the xref:cache.adoc#generating-a-cache-key-with-cachekeygenerator[Generating a cache key with CacheKeyGenerator] section of the Quarkus "Application Data Caching" guide.|For more information, see xref:cache.adoc#generating-a-cache-key-with-cachekeygenerator[Generating a cache key with CacheKeyGenerator].
|
For more information, see the xref:security-openid-connect-web-authentication/.adoc#proof-of-key-for-code-exchange-pkce[PKCE-related section] of the Quarkus "OpenID Connect (OIDC) Authorization Code Flow Mechanism" guide.|For more information, see xref:security-openid-connect-web-authentication.adoc#proof-of-key-for-code-exchange-pkce[OpenID Connect (OIDC) Authorization Code Flow Mechanism].

|====

[[include-source-code-examples]]
== Source code and configuration examples

There are many ways to include source code and examples in the documentation.

The simplest is to write it directly in the file, like this:

@@ -320,7 +373,7 @@ System.out.println("Hello, World!");
-----

In documents like tutorials, you may want to reference source code that is built and tested regularly.
The Quarkus documentation build will copy source files enumerated in `*-examples/yaml` files into a flattened structure in the `target/asciidoc/examples` directory (from the project root).
The Quarkus documentation build copies source files enumerated in `*-examples/yaml` files into a flattened structure in the `target/asciidoc/examples` directory (from the project root).

[source,yaml]
----
@@ -343,7 +396,7 @@ Content copied in this way is referenced by the `\{code-examples}` source attrib
+
`telemetry-micrometer-tutorial-example-resource.java`.

* The source and target file names are declared in `docs/src/main/asciidoc/telemetry-examples.yaml`:
* The source and target file names are declared in `docs/src/main/asciidoc/telemetry-examples.yaml`:
+
[source,yaml]
----
@@ -355,23 +408,24 @@ examples:
* Snippets from this source file are then referenced with the following path:
+
`\{code-examples}/telemetry-micrometer-tutorial-example-resource.java`.
* The source file contains the following comment:
* The source file contains the following comment:
[source,java]
----
// Source: {{source}}
----
* The copied file contains this comment instead:
* The copied file contains this comment instead:
[source,java]
----
// Source: integration-tests/micrometer-prometheus/src/main/java/io/quarkus/doc/micrometer/ExampleResource.java
----

[[document-attributes]]
== Document attributes and variables

[[categories]]
=== Categories

Quarkus documentation is grouped into the following categories.
Quarkus documentation is grouped into the following categories.

.Categories
[cols="<m,<2",options="header"]
@@ -382,7 +436,7 @@ Quarkus documentation is grouped into the following categories.
| business-automation | Business automation integrations
| cloud | Integrations and support for cloud services
| command-line | Command Line Applications
| compatibility | Compatibility with other languages and frameworks
| compatibility | Compatibility with other languages and frameworks
| contributing | Guidance and references to help you contribute to Quarkus.
| core | Information about how the Quarkus works
| data | Topics related to using data sources with Quarkus
@@ -407,10 +461,11 @@ Tag your content to improve findability by adding at least one category to the c
:categories: contributing, data
----

[[document-variables]]
=== Quarkus documentation variables

The following variables externalize key information that can change over time. References
to such information should use the variable inside of curly brackets, `{}`.
The following variables externalize key information that can change over time.
References to such information should use the variable inside of curly brackets, `{}`.

The complete list of externalized variables for use is given in the following table:

@@ -442,5 +497,4 @@ The complete list of externalized variables for use is given in the following ta

|\{graalvm-version}|{graalvm-version}| Recommended GraalVM version to use.
|\{graalvm-flavor}|{graalvm-flavor}| The builder image tag of GraalVM to use e.g. `22.3-java17`. Use a `java17` version.
|===

|===

0 comments on commit 0f5130c

Please sign in to comment.