Back to Guides

バージョン:

Quarkusスタイル・コンテンツガイドライン

ガイドラインは、Quarkus ドキュメントの必要な構造と構成をソースとする明確で一貫性のあるコンテンツを提供するのに役立つように提供されています。

Asciidoc 構文

Quarkusのドキュメントでは、AsciiDoc構文が使用されています。以下のリンクは、AsciiDocの構文と一般的な規約に関する背景を説明しています。

言語・文法

明確で簡潔、かつ一貫性のある技術情報を米国英語で書いて下さい。ローカライゼーション、翻訳、包括性、多様性を考慮し、グローバルな読者のために書いて下さい。以下の文法スタイルを使用するように心がけて下さい：

センテンスの長さ

短い文章は読みやすく、翻訳しやすいです。一文に使う単語数は32語以下になるように心がけましょう。

ウェブサイト掲載

このリポジトリからのコンテンツは、 Quarkus.io ウェブサイトに公開されます。

mainブランチからビルドされたドキュメントは毎晩公開されます(main-SNAPSHOT)。
その他のブランチのドキュメントは、リリース時に公開されます。

タイトルと見出し

コンテンツの種類に関わらず、メインタイトルや文書の見出しは次のようにすることを心がけてください:

目標志向で、読者がなじみのある言葉やキーワードを利用する
説明的で、フィラーワードを避ける
検索エンジンでの検索性を最適化するため、1 行あたり 3〜12 ワード、50〜80 文字程度とする
文章内で大文字を使うスタイルを採用する

タイトルと見出しは、次の表に示すように、Quarkus のコンテンツタイプに固有のガイダンスにも従っている必要があります。

Table 1. Quarkus のさまざまなコンテンツタイプに対応したタイトルガイダンス
Content type	以下を行う必要があります	良い例	悪い例
コンセプト	Start with a noun that names the concept or topic Never start with an active verb, for example, an action word like configure, install, or start Finish the implied sentence: "Understanding …"	Quarkus のセキュリティーと認証メカニズム	Quarkus での反応型 SQL クライアントの発見
ハウツーガイド	Start with an active verb in the imperative verb form, for example, "Create a …" or "Secure a …" Be action-oriented or task-oriented, rather than feature-oriented Finish the implied sentence: "How to …"	WebAuthn 認証による Quarkus アプリケーションのセキュリティー確保	Quarkus での WebAuthn 認証の適用
参考	Use a noun phrase to concisely summarize the content of the document Not include the word 'reference' Finish the implied sentence: "About …"	Hibernate Reactive API の設定プロパティー	Hibernate Reactive API 設定プロパティーを設定するためのリファレンスガイド
チュートリアル	Start with an active verb in the imperative verb form, for example, "Create a …" or "Secure a …" 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 …"	クイックスタートの例を使用して、JVM モードの Quarkus アプリケーションを作成します。	アプリの作成

ファイル規約

ソースの場所

AsciiDocファイルは、 Quarkus GitHubリポジトリの docs モジュール内の src/main/asciidoc ディレクトリにあります。
設定ドキュメントは、Javaソースファイル内のJavaDocコメントから生成されます。
JavaやYAMLなどのソースファイルをAsciiDocのファイルから参照することも可能です。

出力先

設定リファレンス: 設定リファレンスドキュメントは、MicroProfile Config ソースファイルで発見された Javadoc コメントから生成されます。これらの生成されたファイルは（プロジェクトルートから相対で） target/asciidoc/generated/config/ にあります。
AsciiDocのHTMLへの出力: AsciiDocの処理で、 docs/target/generated-docs/ にHTMLファイルを作成します。

テンプレート

コンテンツタイプに適したテンプレートで、新しいドキュメントファイルを作成してください:

コンセプト: docs/src/main/asciidoc/_templates/template-concept.adoc を使用してください
ハウツーガイド: docs/src/main/asciidoc/_templates/template-howto.adoc の使用
参考: docs/src/main/asciidoc/_templates/template-reference.adoc の使用
チュートリアル: docs/src/main/asciidoc/_templates/template-tutorial.adoc の使用

ファイル名

Quarkus ドキュメントはフラットな階層を使用します。

ファイル名の大部分は、そのタイトルを何らかの形で表現する必要があります。すべて小文字で、単語はハイフンで区切り、記号や特殊文字は避けてください。

プレフィックス

関連するドキュメントをグループ化するには、共通の接頭辞を使用します。例えば、Quarkusのドキュメントを書いたり貢献したりすることに関連するドキュメントは、 doc- というプレフィックスを共有します。

接尾辞

ファイル名は、ドキュメントの種類を反映させる必要があります:

コンセプトドキュメントは -concept.adoc で終わる必要があります。
ハウツーガイドは -how.adoc で終わるべきである。
リファレンスは -reference.adoc で終わる必要があります。
チュートリアルは -tutorial.adoc で終わる必要があります。

ドキュメント構造

ドキュメントヘッダー

各ドキュメントは、ドキュメントスコープ属性のヘッダを定義すべきです。最低限，各ドキュメントは，idとタイトルを定義し，共通属性( _attributes.adoc )を含むべきです。

[id="doc-reference"] (1)
= Quarkus style and content guidelines (2)
\include::_attributes.adoc[] (3)
:categories: contributing (4)

1	ファイル名をドキュメントのIDとして使用します。
2	Define the document title following guidance in [Titles and headings].
3	共通のドキュメント属性をインクルードする。
4	Specify the relevant [Categories] (comma separated).

その他の共通ドキュメントヘッダー属性

:extension-status: preview: この属性は、特別なタイプのコンテンツにフラグを立てるために使用します。有効な値: experimental preview , stable (通常は使用しない) , deprecated .
:summary: <text>: サマリーは、ドキュメントの簡潔な（26語以下の）説明を提供するために使用します。この属性の値は、ウェブサイト上のタイルやその他の説明で使用され、アブストラクト (前文) で概説したように、より新しい diataxis スタイルのドキュメントでは必要ありません。存在しない場合、要約の最初の文がタイルのサマリーを生成するために自動的に使用されます。

ドキュメントスコープの属性を扱うときは、空白に注意してください。ドキュメントヘッダーは、最初の空白行で終了します。

アブストラクト (前文)

本文の最初の段落は要約として扱われ、プリアンブルとも呼ばれます。閲覧者がページの目的や意図をすぐに見つけ、理解できるような短い説明を追加します。要約の最初の文はサマリーとなり、 Quarkusガイドのホームページのタイルに自動的に追加されます。

以下のガイドラインを参考にして、要約を書くようにしてください:

ユーザーオリエンテッドである: ユーザーにとって身近な用語やキーワードが含まれている。
簡潔である: 例えば、自己言及的な表現、フィラーワードを避ける。例:
- "This document.."
- "This tutorial…"
- "The following…"
概要: 3 文以内にします。

最初のセンテンスで、コンテンツの価値やいくつかのメリットを26文字以内で説明しているようにして下さい。

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 その他の共通ドキュメントヘッダー属性.

セマンティック改行

段落、リスト、および表のテキストは、^[1] をレビューしやすいように細かく分割する必要があります。各文の終わりで新しい行を開始し、句間の自然な区切りで文自体を分割します。

セクションの使用

セクションのタイトルは、タイトルケースではなく、センテンスケースで記述すること。

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.

深い入れ子 ( ====== Level 4 、 ====== Level 5 ) は、可能な限り避ける必要があります。深くネストされたセクションになってしまった場合は、次のことを考慮してください。

この情報は適切な場所にありますか? 例えば、これがリファレンスであれば、このコンテンツの一部をコンセプトドキュメントやハウツーガイドに移すべきでしょうか?
コンテンツをより消費しやすいように再設定できないか?

コンテンツの種類と構成の詳細については、 Quarkusドキュメントのコンテンツの種類を参照してください。

リンク

In general, prefer 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.

属性を持つ URL マクロリンク

URL マクロは、リンクを別ウィンドウで開くなどの関連性が考えられる追加属性もサポートしています。

https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc Syntax Quick Reference,window=_blank,opts=nofollow]

上記のソースはこのリンクを生み出しました: link: AsciiDoc Syntax Quick Reference.

クロスリファレンス

Quarkus のドキュメントは、いくつかの異なる環境でソースから構築されています。相互参照で属性を使用して、これらの環境全体でドキュメントを構築できるようにします。

Table 2. クロスリファレンスソース属性
属性	説明
`{code-examples}`	収集されたサンプルソースファイルを含むディレクトリーへの相対パス
`{doc-examples}`	ドキュメントガイドのソース例への相対パス
`{doc-guides}`	ドキュメントadocファイルへの相対パス
`{generated-dir}`	生成された設定ファイル `*.adoc` への相対パス。
`{imagesdir}`	イメージが格納されているディレクトリーへの相対パス
`{includes}`	部分的な/再利用可能なコンテンツを含むディレクトリーへの相対パス

コンテンツを相互参照する場合は、常にドキュメント間の xref: 構文を使用し、人間が判読できるラベルをリンクに付けてください。

クロスリファレンス例

xref:{doc-guides}/doc-concept.adoc[Quarkus Documentation concepts] (1)

1	相互参照は `xref:` で始まり、相互参照ソース属性 (`{doc-guides}`)、および読みやすい説明を提供します: `[Quarkus ドキュメントの概念]`

リファレンスソースコード

ドキュメントにソースコードやサンプルを含めるには、さまざまな方法があります。

一番簡単なのは、このようにファイルに直接書き込むことです。

[source,java]
----
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).

examples:
- source: path/to/source/file/SomeClassFile.java (1)
  target: prefix-simplified-unique-filename.java (2)

1	コピーするソースのパスを定義する
2	`target/asciidoc/examples` ディレクトリにファイルをコピーする際に使用する簡略化されたターゲットファイル名を定義します。

この方法でコピーされたコンテンツは、 ../../../_generated-doc/2.16/examples source属性で参照されます。ソースファイル内にリテラル文字列 {{source}} が存在する場合は、コピー先のソースファイルのパスに置き換えられます。

Micrometer例

コピーされる元ファイルは

integration-tests/micrometer-prometheus/src/main/java/documentation/example/telemetry/micrometer/tutorial/ExampleResource.java
docs で使いたいターゲットファイル名は。

telemetry-micrometer-tutorial-example-resource.java.

ソースファイル名とターゲットファイル名は docs/src/main/asciidoc/telemetry-examples.yaml で宣言されます。

examples:
- source: integration-tests/micrometer-prometheus/src/main/java/io/quarkus/doc/micrometer/ExampleResource.java
  target: telemetry-micrometer-tutorial-example-resource.java

そして、このソースファイルからのスニペットは、次のようなパスで参照されます:

{code-examples}/telemetry-micrometer-tutorial-example-resource.java.
ソースファイルには、以下のコメントが記載されています。

// Source: {{source}}

コピーされたファイルには、代わりにこのコメントが含まれています。

// Source: integration-tests/micrometer-prometheus/src/main/java/io/quarkus/doc/micrometer/ExampleResource.java

ドキュメント属性と変数

カテゴリー

Quarkusのドキュメントは、以下のカテゴリーに分類されています。

Table 3. カテゴリー
カテゴリー	説明
`alt-languages`	他の言語、すなわちKotlinとScalaのサポート
`architecture`	Quarkusのランタイムとエコシステム・アーキテクチャ
`business-automation`	ビジネスオートメーション統合
`cloud`	クラウドサービスとの統合・サポート
`command-line`	コマンドラインアプリケーション
`compatibility`	他の言語やフレームワークとの互換性
`contributing`	Quarkusに貢献するためのガイダンスとリファレンス。
`core`	Quarkus の仕組みに関する情報
`data`	Quarkusでのデータソースの使用に関連するトピック
`getting-started`	入門用資料
`integration`	インテグレーションエクステンション（Camel）のサポート
`messaging`	Kafka、AMQP、RabbitMQのようなメッセージングシステムとの統合。
`miscellaneous`	その他
`native`	ネイティブ実行可能ファイルに関する全て
`observability`	ランタイムとアプリケーションのobservabilityを高めるためのエクステンションと統合
`reactive`	リアクティブな技術・技法をサポートするエクステンション
`security`	セキュリティー
`serialization`	シリアル化
`tooling`	ツール
`web`	ウェブ
`writing-extensions`	エクステンションの作成

Tag your content to improve findability by adding at least one category to the categories attribute line in the document header. To add multiple categories, use comma-separated values. For example:

:categories: contributing, data

Quarkus ドキュメント変数

以下の変数は、時間の経過とともに変化する重要な情報を外部化しています。このような情報を参照するには、中括弧で囲まれた {} 内の変数を使用する必要があります。

使用する外部化変数の完全なリストを次の表に示します。

Table 4. 変数
プロパティ名	値	説明
`{quarkus-version}`	`2.16.12.Final`	プロジェクトの現在のバージョン。
`{quarkus-home-url}`	`https://quarkus.io`	プロジェクトのホームページの場所。
`{quarkus-org-url}`	`https://github.com/quarkusio`	プロジェクトの GitHub 組織の場所。
`{quarkus-base-url}`	`https://github.com/quarkusio/quarkus`	Quarkus GitHub の URL の共通ベース接頭辞。
`{quarkus-clone-url}`	`https://github.com/quarkusio/quarkus.git`	ドキュメントで参照されている `git clone` の Quarkus URL。
`{quarkus-archive-url}`	`https://github.com/quarkusio/quarkus/archive/2.16.zip`	メインソースアーカイブへの Quarkus URL。
`{quarkus-blob-url}`	`https://github.com/quarkusio/quarkus/blob/2.16`	ソースファイルを参照するために使用される、メインのブロブソースツリーへの Quarkus URL。
`{quarkus-tree-url}`	`https://github.com/quarkusio/quarkus/tree/2.16`	メインソースツリールートへの Quarkus URL。
`{quarkus-issues-url}`	`https://github.com/quarkusio/quarkus/issues`	Quarkus の課題ページへの URL。
`{quarkus-images-url}`	`https://github.com/quarkusio/quarkus-images/tree`	Quarkus 用に配信されるコンテナーイメージのセットへの Quarkus URL。
`{quarkus-chat-url}`	`https://quarkusio.zulipchat.com`	チャットの URL
`{quarkus-mailing-list-subscription-email}`	`quarkus-dev+subscribe@googlegroups.com`	メーリングリストに登録するために使用される電子メール。
`{quarkus-mailing-list-index}`	`https://groups.google.com/d/forum/quarkus-dev`	メーリングリストのインデックスページです。
`{quickstarts-base-url}`	`https://github.com/quarkusio/quarkus-quickstarts`	Quickstarts URL 共通ベースプレフィックス。
`{quickstarts-clone-url}`	`https://github.com/quarkusio/quarkus-quickstarts.git`	ドキュメントで参照されている `git clone` の Quickstarts URL。
`{quickstarts-archive-url}`	`https://github.com/quarkusio/quarkus-quickstarts/archive/2.16.zip`	メインソースアーカイブへのクイックスタート URL です。
`{quickstarts-blob-url}`	`https://github.com/quarkusio/quarkus-quickstarts/blob/2.16`	メイン blob ソースツリーへのクイックスタート URL。
`{quickstarts-tree-url}`	`https://github.com/quarkusio/quarkus-quickstarts/tree/2.16`	メインソースツリーのルートへのクイックスタートの URL。
`{graalvm-version}`	`22.3`	使用する GraalVM の推奨バージョン。
`{graalvm-flavor}`	`22.3-java17`	使用するGraalVMのビルダーイメージタグ。例: `22.3-java17` 。 `java17` バージョンを使用して下さい。

1. Rhodes, B. Semantic Linefeeds. https://rhodesmill.org/brandon/2012/one-sentence-per-line/