文書スタイル

この記事では、製品ドキュメントにのみ適用されるルールについて説明します。具体的には、6種類のドキュメントの種類とそのテンプレート、複数のLiferayバージョンの扱い方、商用、サポート、またはバージョンステータスを示すバッジ、およびドキュメント固有の用語について解説します。 共通のルールについては、 コアスタイル および 書式設定 を参照してください。 コースについては、 コーススタイル を参照してください。

ドキュメントの種類

文書には6つの種類があり、それぞれに特定の役割があります。

1. はじめに: 階層的にはセクションの最上位に位置し、機能が読者にどのように役立つかを要約する高レベルの説明です。 このセクションでは、現実世界の問題を解決するユースケースに焦点を当て、読者がその機能を最適に活用できるよう、残りのセクションでどのように説明しているかを解説します。

2. コンセプト: トピックが個々の機能やその導入部分以外で詳細な説明を必要とする場合、コンセプト記事がそのギャップを埋めます。 コンセプト記事は、特集記事の前に掲載して前提となる概念を確立したり、特集記事の後に掲載して特集記事内で利用可能なすべての選択肢を説明したりすることができます。 前者の例としては、 コレクションページがあります。後者の例としては、利用可能なすべての ワークフローノード の説明があります。

3. 機能: ドキュメントの基礎。 特集記事では個々の機能を取り上げ、段落や説明を最小限に抑え、番号付きの手順を用いて読者がその機能をどのように使用するかを説明します。 特集記事は、ユーザー向けまたは開発者向けのどちらにもなり得る。 機能に関するドキュメントは、その機能を完全に網羅している必要があります。参照コンテンツ（設定オプション、フィールドの説明など）は、量が少ない場合はインラインで含めることができます。

4. 参照: 機能の構成、設定、オプション、API、およびその他の検索指向の情報を詳細に文書化します。 参考資料の内容が長すぎて特集記事の末尾に含めることができない場合は、独立した記事として掲載すべきです。 参照記事は、必ずそれが裏付けている特集記事からリンクされています。

5. 例: 基本機能のドキュメントを補完します。 機能が十分にシンプルで、機能解説記事と（含まれている場合）参照記事だけで完全に理解できる場合は、例となる記事は不要であり、不必要な冗長性を生み出すだけです。 しかし、その機能が戦略的に重要であったり、様々な方法で利用できたり、ユーザーエクスペリエンスが直感的でない場合、事例は機能の価値を明確にし、顧客による実装を円滑に進めるのに役立ちます。 記事の例には、実際に構築・テストされた、具体的な手順を追った複数の使用例を含めるべきです。 カスタムフィルタの例 および カスタム要素の例 (検索ブループリント用) を参照してください。

6. チュートリアル: 何かを実現する方法を示すことで、拡張ポイント、API エンドポイント、複雑な戦略的機能 (オブジェクトや検索ブループリントなど) を文書化します。 チュートリアルをサポートするデプロイ可能または実行可能なコードは、 article-name/resources/liferay-a1b2.zip フォルダーに格納されています（a1b2 は、リポジトリ内で一意である必要がある 4 文字の英数字シーケンスです）。

文書タイプテンプレート

各文書タイプは、それぞれ特定の構造に従っています。 これらの概要を参考にしてください。

はじめにテンプレート

序文は各セクションの冒頭に置かれ、読者にその内容を理解するための手助けとなる。

# [Topic Name]   (never "Introduction to [Topic]")

[Opening paragraph: what the feature is and the primary value it provides — 2–4 sentences]

[Use cases: what problems it solves and when to use it]

[Prerequisites or required setup, if any]

## [Child Article 1 Title]

[One-sentence description of what this child article covers]

## [Child Article 2 Title]

[One-sentence description]

コンセプトテンプレート

コンセプト記事は、特集記事の前または後に、あるトピックを深く掘り下げて解説する記事です。

# [Concept Name]

[Opening paragraph: what the concept is — 1–3 sentences]

## [Aspect or Sub-topic]

[Explanation]

## [Related Feature or Next Step]

[Link to the relevant feature article]

機能テンプレート

特集記事では、特定の機能とその使い方について説明します。 これは最も一般的な文書の種類です。 参考資料（設定オプション、フィールドの説明など）は、独立した記事として扱うに値するほど内容が充実している場合を除き、特集記事の最後に含めてください。

# [Feature Name or Task Name]

[Opening paragraph: what the feature does, its business value, and when to use it — 1–3 sentences]

[Prerequisites section, if non-obvious setup is required]

1. [Step one]

1. [Step two]

1. [Step three]

## [Additional Options or Configuration Section]

[Description and steps for secondary workflows]

## [Feature Name] Reference

[Include inline here when reference content is small; otherwise split into a separate reference article and link to it]

参照テンプレート

リファレンス記事とは、機能の構成、設定、またはオプションについて説明した文書です。 参考資料の内容が大きすぎて特集記事の末尾に収まりきらない場合は、別途参考記事を作成してください。 特集記事からその記事へのリンクを貼ってください。

# [Feature Name] Reference

[One-sentence description of what is covered — for example, "This reference describes all configuration options for the Foo widget."]

## [Configuration Section or Setting Group]

| Field | Description |
| :--- | :--- |
| [Field Name] | [What it does and any constraints] |
| [Field Name] | [What it does and any constraints] |

## [Another Configuration Section]

[Table or definition list as appropriate]

サンプルテンプレート

サンプル記事では、機能が実際に動作する様子を示す、具体的で構築・テスト済みのユースケースを紹介しています。 各ユースケースは、まず構成またはコードを示し、次に説明を続けます。手順とスクリーンショットは、ユースケースで手動による設定が必要な場合にのみ追加してください。

# [Feature Name] Examples

[What these examples demonstrate and who they help.]

- [Use Case 1 Name](#use-case-1-name)
- [Use Case 2 Name](#use-case-2-name)

See [Using the Feature](./using-the-feature.md) for a full explanation.

## [Use Case 1 Name]

[What this example accomplishes and when to use it.]

[The concrete configuration or code — field/value settings or a JSON or Java snippet.]

[Prose explaining what it does and why.]

## [Use Case 2 Name]

[Description and configuration. Add numbered steps with **Checkpoint:** callouts and screenshots only when the example requires hands-on setup.]

## Related Content

- [Link to the feature article]
- [Links to related reference or concept articles]

チュートリアルテンプレート

チュートリアルでは、拡張ポイント、API、または複雑な機能を使用して何かを実現する方法を説明します。具体的には、動作するサンプルをデプロイし、その仕組みを解説します。 サポートコードは記事の resources/liferay-a1b2.zip フォルダーにあり、 literalinclude を使用して記事に取り込まれます。

# [Task or Extension Point Name]

[What you build and the interface, extension point, or API it demonstrates. Link to the source interface/API and the related feature article.]

## Deploy an Example [Thing]

[Include the run-liferay-dxp environment snippet here with an `{include}` directive. The `_snippets` folder lives under `dxp/`, so point at it with a relative path from the article, for example `../../../../dxp/latest/en/_snippets/run-liferay-dxp.md`.]

1. Download and unzip the example project.

   ```bash
   curl https://resources.learn.liferay.com/[path]/liferay-a1b2.zip -O

   unzip liferay-a1b2.zip
   ```

1. Build and deploy the example.

   ```bash
   ./gradlew deploy -Ddeploy.docker.container.id=$(docker ps -lq)
   ```

1. Confirm the deployment in the Docker container console.

   ```bash
   STARTED com.acme.a1b2.impl_1.0.0
   ```

1. [Exercise the feature in the UI, with screenshots and checkpoints.]

## How the Example Works

### [First Code Element]

[Pull the relevant source from the example project with a `{literalinclude}` directive, for example `./<article-name>/resources/liferay-a1b2.zip/<path>.java` with `:language:` and `:lines:` options.]

[Prose explaining this portion of the code.]

## Conclusion

Congratulations! You now know [what the reader accomplished].

複数のLiferayバージョンを文書化する

ドキュメントはデフォルトで最新バージョンになります。 1つの記事で、1つのメジャーバージョン内の機能のすべてのマイナーバージョンを網羅します。 場合によっては、現在のバージョンと並行して古いバージョンも文書化する必要があります。

• Liferayが機能のユーザーインターフェースを変更する場合。
• Liferayが機能を非推奨または削除したにもかかわらず、読者が依然として古いバージョンを使用している場合。
• Liferayが既存の機能に新しい機能を追加する場合。

このような場合は、同じ記事内で複数のバージョンをサポートしてください。 それを実現する方法をいくつかご紹介します。

• マイナーバージョンの変更点について議論するために、新しい記事を作成しないでください。 同じメジャーバージョンのコンテンツはすべて同じ記事にまとめてください。

• 最新の情報は記事の冒頭に、最も古い情報は末尾に配置してください。

• 変更による影響を評価する：

  • 軽微な変更の場合は、 バージョンバッジ を使用して、コンテンツがどのバージョンに適用されるかを読者に知らせます。 変更内容にヘッダーが必要な場合は、ヘッダーの直後にバッジを配置してください。
  • 大きな変更については、専用のH2セクションを使用して変更点について説明し、記事の冒頭にH2セクションへの相互リンクを含む注釈形式の注意書きを配置してください。

バッジ

ドキュメントバッジは 4 つあります: サブスクリプション、 サポートされていない、 バージョン、および 機能フラグ。 これらを使用して、記事やセクションを適切にマークしてください。

変更通知を受け取る（購読する）

Liferay DXP Enterpriseサブスクリプションでのみ利用可能で、無料ティアでは利用できない機能にマークを付けます。

<span class="bdg bdg-primary">Subscription</span>

サポート対象外

存在するがサポートされていない機能に印を付けてください。

<span class="bdg bdg-warning">Unsupported</span>

バージョン

製品の特定のバージョンにのみ存在する機能をマークしてください。

<span class="bdg bdg-secondary">7.4 U15+ and GA15+</span>

機能フラグ

フィーチャーフラグ によって制限されているフィーチャーには、フラグのステージ名とフィーチャーフラグリファレンスの対応するセクションへのリンクを含むリンクバッジを付けます。 該当するステージを選択してください。

<span class="bdg bdg-link-primary">[Beta Feature](../../security-and-administration/administration/configuring-liferay/feature-flags.md#beta-feature-flags)</span>

<span class="bdg bdg-link-primary">[Dev Feature](../../security-and-administration/administration/configuring-liferay/feature-flags.md#dev-feature-flags)</span>

<span class="bdg bdg-link-primary">[Release Feature](../../security-and-administration/administration/configuring-liferay/feature-flags.md#release-feature-flags)</span>

feature-flags.md への相対パスは、ツリー内の記事の深さに依存します。現在の記事から ../ セグメントを数えます。 機能が一般提供段階に移行したら、バッジを削除します。

バッジの詳細については、 Sphinx Design ドキュメント を参照してください。

慣用句

文書固有の専門用語。 すべてのコンテンツに適用される共通のフレーズ規則については、 コアスタイル を参照してください。

「～のために設計された」

というフレーズは が不要になるように設計されている。 そのソフトウェア、プロセス、またはコンポーネントが直接的に行う動作を記述してください。 同じことが同類にも当てはまります。 はを目的とし、 はを目的とし、 は用に構築され、 は に合わせて調整されています。

問題点：このシステムはカスタムワークフローをサポートするように設計されています。

良い点：このシステムはカスタムワークフローをサポートしています。

悪い点：これらのプロセスは、古いデータのみに影響を与えるように設計されています。

良い点：これらの処理は、古いデータのみに影響を与えます。