フィードバックを送信
Liferay Style Guide
ご覧のページは、お客様の利便性のために一部機械翻訳されています。また、ドキュメントは頻繁に更新が加えられており、翻訳は未完成の部分が含まれることをご了承ください。最新情報は都度公開されておりますため、必ず英語版をご参照ください。翻訳に問題がある場合は、 こちら までご連絡ください。

文書スタイル

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

ドキュメントの種類

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

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

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

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

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

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

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

文書タイプテンプレート

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

はじめにテンプレート

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

# [トピック名] (決して "[トピック] の概要"とはしない)

[冒頭の段落: 機能の内容と主な価値 — 2〜4 文]

[ユース ケース: どのような問題を解決し、いつ使用するか]

[前提条件または必要なセットアップ (ある場合)]

## [子記事 1 のタイトル]

[この子記事で扱う内容を 1 文で説明]

## [子記事 2 のタイトル]

[一文での説明]

コンセプトテンプレート

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

# [概念名]

[冒頭段落：概念の内容 — 1～3文]

## [側面またはサブトピック]

[説明]

## [関連機能または次のステップ]

[関連機能記事へのリンク]

機能テンプレート

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

# [機能名またはタスク名]

[冒頭の段落: 機能の内容、ビジネス上の価値、および使用時期 — 1～3 文]

[前提条件セクション、分かりにくい設定が必要な場合]

1. [ステップ1]

1. [ステップ２]

1. [ステップ 3]

## [追加オプションまたは設定セクション]

[二次ワークフローの説明と手順]

## [機能名] リファレンス

[リファレンスの内容が小さい場合はここにインラインで含めます。そうでない場合は、別のリファレンス記事に分割してリンクします]

参照テンプレート

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

# [機能名] リファレンス

[対象となる内容の 1 文の説明 — 例: "このリファレンスでは、Foo ウィジェットのすべての構成オプションについて説明します。"]

## [構成セクションまたは設定グループ]

| フィールド | 説明 |
| :--- | :--- |
| [フィールド名] | [その機能と制約] |
| [フィールド名] | [その機能と制約] |

## [別の設定セクション]

[必要に応じて表または定義リスト]

サンプルテンプレート

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

# [機能名] 例

[これらの例が示す内容と、誰に役立つか。]

- [ユースケース 1 名](#use-case-1-name)
- [ユースケース 2 名](#use-case-2-name)

詳細については、[機能の使用方法](./using-the-feature.md) を参照してください。

## [ユースケース1名]

[この例が達成することと、いつ使用するか。]

[具体的な設定またはコード ― フィールド／値の設定、またはJSONやJavaのスニペット。]

【その機能と理由を説明する文章】

## [ユースケース 2 名前]

[説明と構成。 手順番号を記載した「**チェックポイント:**」を追加してください。例で実際に設定作業が必要な場合のみ、注釈とスクリーンショットを使用してください。

## 関連コンテンツ

- [特集記事へのリンク]
- [関連する参考記事または概念記事へのリンク]

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

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

# [タスクまたは拡張ポイント名]

[構築するものと、それが示すインターフェース、拡張ポイント、またはAPI。 ソースインターフェース/APIおよび関連する特集記事へのリンク。

## サンプル [Thing]

[ここに `{include}` ディレクティブを使用して run-liferay-dxp 環境スニペットを含めます。 `_snippets`フォルダは`dxp/`の下にあるので、記事からの相対パスで指定してください。例えば、`../../../../dxp/latest/en/_snippets/run-liferay-dxp.md`のように指定します。

1. サンプルプロジェクトをダウンロードして解凍してください。

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

   unzip liferay-a1b2.zip
   ```

1. サンプルをビルドしてデプロイします。

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

1. Dockerコンテナコンソールでデプロイを確認してください。

   ```bash
   開始 com.acme.a1b2.impl_1.0.0
   ```

1. [スクリーンショットとチェックポイントを用いて、UI上でこの機能を実際に操作してみてください。]

## 例の動作方法

### [最初のコード要素]

[`{literalinclude}` ディレクティブを使用して、例のプロジェクトから関連するソースを取得します。たとえば、`./<article-name>/resources/liferay-a1b2.zip/<path>.java` に `:language:` と `:lines:` オプションを指定します。]

[このコード部分を説明する文章。]

## 結論

おめでとうございます！ これで読者が何を成し遂げたのかが分かりましたね。

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

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

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

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

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

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

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

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

バッジ

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

サブスクリプション

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

<span class="bdg bdg-primary">購読</span>

サポート対象外

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

<span class="bdg bdg-warning">サポートされていません</span>

バージョン

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

<span class="bdg bdg-secondary">7.4 U15+ および GA15+</span>

機能フラグ

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

<span class="bdg bdg-link-primary">[ベータ版機能](../../security-and-administration/administration/configuring-liferay/feature-flags.md#beta-feature-flags)</span>

<span class="bdg bdg-link-primary">[開発者向け機能](../../security-and-administration/administration/configuring-liferay/feature-flags.md#dev-feature-flags)</span>

<span class="bdg bdg-link-primary">[リリース版機能](../../security-and-administration/administration/configuring-liferay/feature-flags.md#release-feature-flags)</span>

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

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

慣用句

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

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

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

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

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

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

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

構成設定の参照

読者に設定項目の場所を伝える際は、該当項目への完全かつ検証済みのナビゲーションパスを提示してください。 読者が直接目的の項目にたどり着けるよう、表面名、カテゴリ名、項目名を明記してください。

悪い例：システム設定を開き、「コラボレーションへの招待」を検索してください。

良い方法: コントロール パネル → インスタンス設定 → 共有で、 コラボレーションへの招待 エントリを開きます。

設定は、その範囲に応じて、インスタンス設定、システム設定、またはサイト設定に表示されます。そのため、適切な表示場所を指定してください。