コアスタイル

Liferayは、様々な状況にある多くの読者向けに、ドキュメントやコースを提供しています。 両者とも同じ声質、同じ言葉遣いが見られる。 この記事では、共通の文体、文章を簡潔かつ予測可能なものにするための言い回しのルール、そしてコンテンツの構成方法を規定する普遍的な原則について定義します。

テキストの書式設定、コードブロック、リスト、表、見出し、画像、および警告については、 書式設定 を参照してください。 製品ドキュメントにのみ適用されるルールについては、 ドキュメントスタイル を参照してください。 コースにのみ適用されるルールについては、 コーススタイル を参照してください。

このガイドの使い方

Liferayのスタイルは、 『シカゴ・マニュアル・オブ・スタイル』 や、ストランクとホワイトの 『スタイルの要素』といった巨人の肩の上に成り立っています。 このガイドに記載されていない事項については、それらの指示に従ってください。

ルールにはそれぞれ異なる重みがある。

• 必須: 必須。 それに違反することは明らかな誤りである。 例：未来形は使わない、常にオックスフォード・コンマを使う、読者に役割を押し付けない。
• 推奨: 強く推奨します。 逸脱には具体的な正当化理由が必要です。 例: 「simply」や「just」は避け、単数形の theyよりも複数形の構文を優先します。
• 5月: 適切な判断があれば代替案が許容される慣習またはベストプラクティス。 例：短縮形の使用、編集者の選択。

2つの規則が矛盾する場合は、より具体的な規則を優先してください。 既知の競合については、 既知の例外とタイブレーカー を参照してください。

声とトーン

その声は親しみやすく、気さくで、率直だ。 Liferayのコンテンツには多くのライターが寄稿していますが、全体を通して一人の人物の声が感じられるようにする必要があります。

フレンドリー

文章は親しみやすいものであるべきだ。 Liferayは多くの製品やサービスと連携しており、それらはすべて平等に扱われるべきである。 Liferayは他の製品と比較されることは決してなく、特定の統合製品の使用を前提としないように注意する必要があります。 一般的な例を挙げてください。

Foo Engine の設定を完了するには、アプリケーション サーバーの JVM で -Djavax.net.fooey=fooey:verbose を設定します。 Tomcatでは、オプションは CATALINA_OPTS に setenv.shで追加されます。

CATALINA_OPTS="$CATALINA_OPTS -Djavax.net.fooey=fooey:verbose"

それ以外については、他の製品のドキュメント作成は避けてください。 クラスタリングに関する記事では、Liferayをクラスタ環境で動作させるために必要な設定のみを記述し、Liferay独自のDockerコンテナ以外のアプリケーションサーバー自体については記述しないでください。

カジュアル

英語を母国語としない人でも読みやすいように、くだけた文体で書いてください。 形式ばった表現や不必要に難しい言葉遣いは避けましょう。 語数を減らし、文章の流れをスムーズにするために、短縮形の使用をお勧めします。

直接

あなたはたった一人の読者に向けて話しているのであり、その読者にはやるべき仕事がある。 要点を述べてください。 以下の Liferay フレーズ ルールは、その直接性を強制するために存在します。未来形、「simply」や「just」の使用、「the following」を目的語なしで使用することはできません。

読者へのメッセージ

常に you (または命令形では暗黙の「you」) を使用します。 読者に対して、特定の役割、肩書き、または職務内容を押し付けてはいけません。

問題：管理者がディレクトリを作成できてしまう。

良い点：ディレクトリを作成します。 または ディレクトリを作成できます。

悪い例: マーケターはフラグメントを使用して…

良い: フラグメントを使用して…

読者向けの文章では we を避けてください。 let's [do something] とは言わないでください。

例外: このスタイルガイドなどのメタドキュメントでは、 Liferay という組織を代表して発言する場合、 を使用する場合があります。 名前付き UI 要素のラベルは、ラベルに本来禁止されている単語が含まれている場合でも、表示されているとおりに正確に再現されます (たとえば、 Let's Go! というラベルのボタン)。 （シリーズ作品として）。

ソフトウェアが制御しているわけではない

読者に力を与えるべきであり、製品に力を与えるべきではない。 読者が行動を起こす。製品はそのための道具である。

悪い点: この機能を使うとレコードを作成できます。

良い点：記録を作成できます。 または この機能を使用してレコードを作成します。

悪い点：フィールドを設定できるダイアログが表示されます。

良い方法：ダイアログを使用してフィールドを設定します。

ソフトウェアの動作を曖昧にしてはいけない

ソフトウェアが実際に何をするのかを説明してください。何ができるかではなく、何をするかを説明してください。 曖昧な表現（ はであるべきである、 かもしれない、かもしれない、 かもしれない、のように見える、 は のように見える）は、実際にはその行動が既知で一貫している場合、読者を誤解させる可能性があります。 ソフトウェアがその処理を行うか、行わないかのどちらかです。どちらかを選んで、そのように記述してください。

問題：インストーラーをEclipseにドラッグすると、インストールが開始されるはずです。

良い点：インストーラーをEclipseにドラッグすると、インストールが開始されます。

動作が本当に条件付きである場合は、曖昧な表現を使うのではなく、その条件を明確に示してください。

問題：このコマンドは、ネットワーク速度が遅い場合、失敗する可能性があります。

良い点：このコマンドは、リクエストが30秒のタイムアウトを超えると失敗します。

は と は 使用して ガイドの使い方 のルールレベルを示すことができますが、これらはメタドキュメントの慣例であり、このルールの対象ではありません。

能動態と現在形

能動態を使用してください。 現在形を使用してください。未来形は使用しないでください。

問題：この操作を行うと、データベースに新しいレコードが作成されます。

良い点：この操作により、データベースに新しいレコードが作成されます。

段落ではなく手順で

可能な限り、手順に関する事項は文章で記述するのではなく、番号付きのステップに分割してください。 段落の中に埋もれた情報は見つけにくい。 番号付きの手順は、読者（およびLiferayサポート）が問題が発生した正確な手順を特定するのに役立ちます。

不要な言葉は省く

『スタイルの要素』 からのこのルールはマントラです。 以下の文法規則では、ほとんどの場合きれいに省略できる特定の単語や構文を挙げています。

慣用句

オックスフォード・コンマ

3つ以上の項目を列挙する場合は、オックスフォード・コンマ（連続コンマ）を使用してください。 接続詞の前のコンマは、誤読を防ぎます。

指導してくださった方々、両親、そして大統領に感謝申し上げます。

あなたのメンターは本当にあなたの両親と大統領ですか？ オックスフォード・コンマを使うことで、曖昧さが解消されます。

指導してくださった方々、両親、そして大統領に感謝申し上げます。

未来時制

未来形は使用しないでください。 現在形はほとんどの場合有効です。

問題：この操作を行うと、データベースに新しいレコードが作成されます。

良い点：この操作により、データベースに新しいレコードが作成されます。

「しなければならない」であって、「必要」ではない

は よりも短く強く、 が必要です。 一言で二言より勝る：

悪い点：アセットを使用するには、アセットレンダラーとアセットレンダラーファクトリが必要です。

良い点：アセットを使用するには、アセットレンダラーとアセットレンダラーファクトリが必要です。

「クリック」であって「クリックオン」ではない。

は を他動詞として使用します。 は に対して使用しません。

悪い: をクリックして を保存します。

良い: をクリックして保存 します。

悪い点：結果を絞り込むには、エンティティをクリックしてください。

良い点：エンティティをクリックすると、結果が絞り込まれます。

決して「単に」や「ただ」とは言わない

を単に または を単に として使用しないでください。 あなたにとって単純なことでも、読者にとっては単純ではなく、言葉は何の役にも立たない。

曖昧な「ザ・フォロイング」

次の というフレーズは、明示的な目的語がないため曖昧です。

悪い例：以下のことを行ってください。

代わりに特定の構文を使用してください。

良い: 次の手順に従ってください: または 次のことを行います:

「ここにあります」という表現は避けてください。

ここに (そして ここに) はリストを導入する弱い方法です。 主題から始める方が良いでしょう。

悪い点：変更されたプロパティは以下のとおりです。

良い点：これらの特性が変更されました：

悪い例：利用可能なオプションは以下のとおりです。

良い点：以下のオプションが利用可能です：

結腸

コロンは独立節の後にのみ使用してください。 以下の用法は誤りです。コロンをコンマに置き換えるか、構造を修正してください。

• 悪い例：アクセラレーターを使う場合：
• 悪い例: サイトを作成するには:
• 悪い例：

エムダッシュ、セミコロン、括弧

ダッシュ、セミコロン、括弧は控えめに使用してください。 それぞれが文を中断して節を脇に置く役割を果たします。文が複数の節に依存している場合は、文を二つに分割します。

メタ情報

ドキュメントについて決して記述してはいけません：

• 悪い: この記事は… を目的としています
• 悪い点: この一連のチュートリアルでは、… をご案内します。
• 悪い点: Liferayでは、私たちは…

これは埋め合わせです。 代名詞は厳密に あなた に限定し、冠詞、セクション、形式については言及しないでください。

クロスリンクの文言

ある記事から別の記事へリンクを張る際は、リンクに説明文を付けてください。「この記事」や「ここをクリック」といった表現は避けてください。

不適切：詳細については、こちらの記事をご覧ください。

良い点: 詳細については、 フレンドリー URL を参照してください。

内部トラッカー参照

Liferay Jira チケット参照（ LRDOCS-XXXXX、 LPS-XXXXX、 LPD-XXXXX、 COMMERCE-XXXXXなど）は、このページで読者が何らかの操作を行う際にリンク先のチケットが役立つ場合にのみ、控えめに使用してください。 基準となるのは、状況に応じた有用性であり、可視性ではない（これらのチケットの多くは一般公開されている）。

• 役立つ — 維持: 破壊的変更と非推奨の参照ページでは、特定の LPD- / LPS- チケットを参照しているため、技術的な読者はチケットの GitHub 参照を介して変更を基となるコードまで追跡できます。 それが正統的な使用例です。
• 役に立たない — 削除: 内部ステータス チケットを指す記事の警告または相互リンク (「フォローアップ プランについては LRDOCS-XXXXX を参照してください」)。 読者はトラッカーのステータスに基づいて行動することはできません。読者が求めているのは、記事自体が正確で最新の情報であることです。

デフォルトでは、文章中のトラッカー参照を省略する。 このページにおいて、リンク先のチケットが読者の障害を効果的に解消する場合にのみ、それらを含めてください。 主張の根拠が、公開されている変更点に関するページや別の記事である場合は、そのページへのリンクを貼ってください。

数字を含める

シカゴ・マニュアル・オブ・スタイルによると、10 以下の数字は書き出し、11 以上の数字は数字を使用します。

選択肢は6つあります。

16進数には16の桁があります。

主語と代名詞の一致

主語は複数形を推奨します。 複数形を使うことで、単数形の代名詞を使う際の不自然な選択を避けられ、通常はより短い文になる。

あまり好ましくない点：各ユーザーは、それぞれの状況に応じて結果を見る。

望ましい状態：ユーザーは、自身の状況に応じて結果を確認できる。

単数形の they は シカゴで受け入れられているが、複数形の方がより明確である。

あまり好ましくない：ユーザーがこの機能を実行すると、フィードバックが表示されます。

望ましい動作：ユーザーがこの機能を実行すると、フィードバックが得られる。

"どれでも"

ほとんどの場合、 または は意味を変えずに削除できます。

使用しているテーマにスタイルブック用のトークン定義がない場合、ページ上のカラーピッカーの設定はすべてカラーパレットの設定に置き換えられます。

や がなくても、文は同じです。 切ってください。

ソフトウェアが動作する際に「自動的に」

文章が既にソフトウェアが実行する動作を説明している場合、 は自動的に が暗黙のうちに示されます。 それを捨てろ。

問題点：有効にすると、Liferay DXPは新しい仮想インスタンスごとに専用のスキーマを自動的に作成します。

利点：有効にすると、Liferay DXPは新しい仮想インスタンスごとに専用のスキーマを作成します。

原因と結果の連鎖（「有効になると、 … が作成する」）は、システムが自律的に動作することをすでに示しています。 単独で 、単独で 、介入なしで の場合も同様です。文が既に作業を行うソフトウェアを説明している場合、修飾語は何も追加しません。

例外は、 が自動的に を手動による代替手段と明確に区別する場合です。たとえば、「スキーマは自動的に作成されるため、スクリプトを実行する必要はありません。」

曖昧な修飾語

意味を付加しない修飾語句（例： 現在、 まだ、 両方など）を削除します。

悪い点：この機能は現在、サイドバーで利用可能です。

良い点：この機能はサイドバーから利用できます。

問題：条件が発生した際に通知が送信されてしまう。

良い点：条件が発生したときに通知が送信されます。

問題：XとYの両方が発生したときに通知が送信される。

良い点：XとYが発生したときに通知が送信されます。

修飾語は、読者が必要とする情報を伝える場合にのみ使用してください。

動詞と副詞の組み合わせとその名詞

動詞と副詞の組み合わせは2語で、対応する名詞は1語です。 それらを正しく理解しましょう：

動詞-副詞	名詞
分解するには（どのように？）	簡単に説明すると
設定するには（どのように？）	これはグラフィカルなセットアップルーチンです
ログインするには（どうすればいい？）	ログイン情報を絶対に他人に教えないでください

もし/ならば

BASICでは、 が に を必要とする場合、が実行されます。 英語の散文では、通常はそうではない。 を削除してから を削除します。

動詞構文

動詞構文を分割しないでください。

オリジナル	優先
異なるページを動的に表示する	異なるページを動的に表示する
最適には囲むことができる	最適に囲まれることができる

主題と参照に関する合意

単数形と複数形の主語と指示対象が一致していることを確認してください。

誤り：位置情報データベースには、IPアドレスとその発信国とのマッピングが含まれています。

正しい：位置情報データベースには、IPアドレスとその発信国とのマッピング情報が含まれています。

普遍的な組織原理

これらの原則は、文書作成とコースの両方に当てはまります。

機能別ではなく、ユーザーの目標別に整理する

読者が達成しようとしていることを中心にコンテンツをグループ化し、それをサポートするLiferayの機能名を中心にグループ化しないようにしてください。 目標主導型の組織は、機能の仕組みよりも、ベストプラクティスと成果に焦点を当て続けます。

悪い（機能重視型）	良い（目標主導型）
フラグメント	ページ要素
ライフレイフラグメント	モジュール式ページ要素
フラグメントの使用	再利用可能なコンポーネントを使用してページを構築する
スタイルブック	サイトの外観と操作性
Liferayスタイルブック	サイトテーマのカスタマイズ
スタイルブックの作成	ブランドスタイルの適用
オブジェクト	カスタムデータモデル
Liferay Object	データ構造のモデリング
カスタムオブジェクトの作成	Liferay DXPの拡張

この原則はもともと講義内容に関して明確にされたものであるが、製品ドキュメントの特集記事にも同様に適用できる。

ハッピーパスファースト

読者が初めてタスクを実行する際には、最も簡単で推奨される手順を順を追って説明してください。 特殊なケース、高度な設定、代替ツールについては、後のセクションで説明します。 まず順調に進む道を選んだ読者は、高度な領域に進む前に、まずは実用的な成果を得ることができる。

自己完結型記事

各記事はそれぞれ独立した内容であるべきです。 読者が同じテーマに関する別の記事を読んだことがあると決して思い込まないでください。 相互リンクが役立つ場合は含めても構いませんが、次のような表現は避けてください。

悪い点: Foos に関する記事の画面下部にある大きな赤いボタンに気づいたかもしれません。 これがその機能です。

良い点： フォーム の下部には、この別の機能があります。 使い方は以下のとおりです。

遺物を直接記述する

設定ファイル、プロパティファイル、マニフェスト、または読者が操作するあらゆる成果物を紹介する場合は、まずその成果物 が であり、どのように使用するのかを説明します。 他のアーティファクトがそれについて述べている内容を記述しないでください。

悪い点: コミットされた foo.properties ファイルは、編集しないように指示しています。

良い点: foo.properties ファイルには、ビルド フラグとデフォルト値が記録されています。 デフォルト設定を上書きするには、兄弟ファイル foo.[user-name].properties を作成します。

読者が関心を持っているのは、その人工物の目的と、それに対する次の行動であって、別ファイルにある文章ではない。

「… の紹介」は決してありません

記事のタイトルを [トピック] の紹介 にしないでください。 タイトルはテーマそのものにしてください。

ドキュメントはマーケティングではない

手順によって何が生じるかを、中立的かつ技術的な用語で説明してください。 商業的な影響について論評しないでください。例えば、ソースコードからビルドすると「ライセンス要件なし」のLiferay DXPが生成される、といった点を強調しないでください。 Liferayの商用メッセージは価格ページで扱われており、技術的な内容がそれを損なわないようにする必要があります。 もし文章が、有料の代替手段よりも特定の方法を推奨しているように読める場合は、書き直すか削除してください。

用語

用語は一貫性を保つこと。 迷ったときは、調べてみましょう。

間違っている	右揃え
バックエンド	バックエンド
フロントエンド	フロントエンド
JavaScript（またはJSまたはjs）	JavaScript
サービスビルダー	サービスビルダー
RESTビルダー	RESTビルダー
openapi	OpenAPI
インデックスの再作成	再インデクス
[LIFERAY_HOME]	[Liferay Home]
型破り	型破りな
フリーマーカーまたはフリーマーカー	FreeMarker
ドロップダウン	落ちる
Liferayポータル（散文）	Liferay DXP

最後の項目は重要です。 Liferay DXP が製品です。 Portal という単語は、ソースリポジトリ名 (liferay-portal用に予約されています。読者向けの文章には使用しないでください。

ルールの適用範囲

このガイドに記載されているルールのほとんどは、あらゆるコンテンツタイプに適用されます。 以下の規則は適用範囲を狭めています。

• 「私たち」や「～しましょう」は使用しません: すべての読者向けコンテンツに適用されます。 このスタイルガイドなどのメタドキュメントでは、Liferay という組織を代表して発言する場合、 私たち を使用することがあります。
• 名前付きUI要素ラベル： ラベルに本来禁止されている単語が含まれている場合でも、インターフェースに表示されているとおりに正確に再現します。 これはすべてのコンテンツタイプに適用されます。
• タイプ固有の表現: ドキュメントとコースでは、いくつかの表現ルールが異なります (たとえば、 設計目的)。 これらは、各タイプファイルの「用語集」セクションに個別に記載されており、ここでは記載されていません。コアは共通の用語集のみを扱っています。

既知の例外事項とタイブレーカー

競合	解像度
「いいえ ‘行きましょう」と書かれたボタン 行きましょう!	UI要素名は完全に再現されます。 レーベル側の勝ちだ。
「いいえ ‘私たちは」 vs. メタドキュメント	メタドキュメントでは、組織の表現として や を使用する場合があります。
単数形 彼ら と複数形の構文	どちらもシカゴ標準語 に従って文法的に正しいです。 複数形を推奨します。単数形 they は、複数形に書き換えるのが不自然な場合に許容されます。
シカゴ・マニュアル・オブ・スタイル とこのガイドの比較	このガイドは、Liferay固有の慣例に関して優先されます。 このガイドに記載がない場合は、 シカゴ を参照してください。

フィードバック

不明な点や納得できない点がある場合は、 Liferay Discuss を通じてフィードバックを送信してください。 ここで示されている基準は、長年にわたるコンテンツの定義、テスト、改良の結果ですが、完璧ではありません。