コアスタイル

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

テキストの書式設定、コードブロック、リスト、表、見出し、画像、および警告については、 書式設定 を参照してください。製品ドキュメントにのみ適用されるルールについては、 ドキュメントスタイル を参照してください。コースにのみ適用されるルールについては、 コーススタイル を参照してください。講師主導のトレーニングでは、トークトラックが音声であるため、いくつかのルールが逆転します。 講師主導のトレーニング を参照してください。

このガイドの使い方

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

各規則は、それぞれの言葉でその効力を明確に示している。絶対にしない および 例外のないルールを マークしない、 推奨 および 特定の理由で上書きできる強力なデフォルトを マークしない。

Valeは一部のルールを自動的にチェックし、プルリクエストに結果を報告します。ヴェイル社が違反をどれほど大々的に報告するかは、違反の深刻さとは別の問題である。なぜなら、それはチェックシステムが実際の違反と正当な例外をどれほど確実に区別できるかにも左右されるからだ。例外規定のないルールであっても、チェックで誤検出が発生した場合は警告として報告される可能性があります。

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」) を使用します。読者に対して、特定の役割、肩書き、または職務内容を押し付けてはいけません。

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

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

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

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

読者に対しても、自分の意見や反応を押し付けてはいけません。読者の考えを勝手に決めつけて訂正するのは、読者の発言を歪曲する行為だ。

悪い点：この枝は残り物ではありません。トランスフォーマーは、両方のエディタバージョンの設定を受け取ります。

良い点：このトランスフォーマーは、CKEditor 4とCKEditor 5の両方のエディタの設定を受け取ります。

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

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

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

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

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

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

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

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

「Can」を落とさないでください

読者ができることを説明するときは、 can を使用してください。それを省略すると、能力が命令や単なる事実の記述になり、意味が変わってしまう。

悪い例：オブジェクトのフィールドを自分で定義する。

良い点：オブジェクトのフィールドを定義できます。

読者が何らかの手順を実行する場合は、命令形を使用してください。なぜなら、それは指示を意味するからです。

良い: オブジェクトのフィールドを定義し、 保存 をクリックします。

テストのポイントは、その文が読者が現在行っている選択肢や行動を記述しているかどうかです。オプションは を保持し、 を保持します。

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

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

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

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

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

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

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

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

能動態と現在形

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

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

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

段落ではなく手順で

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

不要な言葉は省く

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

冗長な文章は避ける

難解な文章は、主節、傍白、同格語句など、要素が多すぎる過度に複雑な文から生じる。一つの文にあまりにも多くのアイデアを詰め込むと、読者に負担をかけてしまう。これらの文を分割してください。

一つの文に二つの主要なアイデアだけを含めるようにしてください。

悪い点: トランスフォーマーはツールバーの項目に区切り文字 ('|') と 'style' を追加しますが、 style が既に存在しない場合に限ります。そのため、スタイル ドロップダウンが常にツールバーに表示されます。

良い点: トランスフォーマーは、'|') と 'style' をツールバーの項目に追加します。ただし、 style がまだ存在しない場合に限ります。これにより、ツールバーに「スタイル」ドロップダウンが常に表示されるようになります。

主語と動詞を最初に記述する

主語や動詞を埋もれさせてはいけません。長い冒頭句は要点を伝えるのを遅らせ、括弧付きの同格句を多用すると文章の流れが途切れてしまう。

悪い点: トランスフォーマーは設定オブジェクトと標準の DOM API のみで動作するため、拡張機能には @ckeditor パッケージは必要ありません。

良い点: @ckeditor パッケージを含める必要はありません。トランスフォーマーは設定オブジェクトと標準の DOM API のみで動作するためです。

慣用句

アメリカ式綴り

アメリカ英語の綴りを使用してください。 color、 behavior、 organize、および licenseを書き、 colour、 behaviour、 は書きません。を組織するか、 ライセンス を取得します。

文間隔

ピリオドの後にはスペースを1つだけ入れ、2つ入れてはいけません。

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

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

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

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

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

未来時制

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

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

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

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

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

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

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

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

を を他動詞として使用し、 を の上に使用しません。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

結腸

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

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

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

ダッシュ記号（em dash）は絶対に使用しないでください。代わりに文を書き直してください。2つの文に分けるか、コンマまたはピリオドを使用してください。

悪い点：価格表で単価が設定され、プロモーションによって後から調整される。

良い点：価格表によって単価が定められている。プロモーションは後で調整します。

ダッシュ記号を使うのは、たいていの場合、その文が情報過多であることを意味する。ダッシュを取り除くと、それが隠していた構造が明らかになるため、これは句読点の規則であるだけでなく、表現上の規則でもあるのです。

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

メタ情報

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

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

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

クロスリンクの文言

ある記事から別の記事へリンクを張る際は、「この記事」や「ここをクリック」ではなく、説明的なテキストをリンクに付けてください。

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

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

説明的なリンクテキストはそれ自体で意味を成します。リンクの後に「詳細については」や「その流れについては」などの語句を追加しないでください。これらの語句は、リンクテキストが既に伝えている内容に何も付け加えるものではありません。

内部トラッカー参照

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

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

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

数値

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

選択肢は6つあります。

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

主語と代名詞の一致

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

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

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

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

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

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

"どれでも"

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

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

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

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

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

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

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

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

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

曖昧な修飾語

意味を付加しない修飾語句、例えば 現在、 まだ、および 両方 などを削除します。

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

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

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

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

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

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

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

歴史的枠組み

製品が現在どのように動作するかを説明してください。は以前はであり、 は以前はであり、 は以前はであり、 は最新リリース 以降削除されました。それらは時代遅れで、現代の読者にとって何の付加価値ももたらさない。

問題点：以前は「インスタンス設定」にあった設定項目が、「構成」に移動しました。

良い点：設定は「構成」の中にあります。

例外は、主題が であり、変更が であるコンテンツです。非推奨に関する説明、互換性のない変更に関するページ、アップグレードに関する記事は、読者に何が変更されたかを伝えるために存在し、そこに履歴こそが情報である。

専門用語名詞

surface を製品内の場所を意味する名詞として使用しないでください。また、 exercise をテストまたは実行を意味するものとして使用しないでください。どちらも、読者が特定しなければならない特定の事柄を隠している。物の名前を挙げるか、あるいは単純な動詞を使ってください。

問題：このキーは、バンドルされているLiferayサーフェスに属しています。

良い点：鍵となるのは、ページフラグメント内のリッチテキストエディタです。

悪い例: Alloy Editor ブランチを実行するには、キーを変更します。

良い: Alloy Editor ブランチをテストするには、キーを変更します。

どちらも同じ習慣だ。つまり、ごく普通の単語を専門用語として再利用しているのだ。もう1つの形式は、名詞を動詞として用いるもので、例えば リクエスト を実行する、または 機能を 終了する、といったものです。どちらも、それを考案したチーム以外の人にとっては、内部用語として理解されるだろうし、平易な表現の方が読むのが速い。

造語

造語はするな。 De-risk は型ケースです。一般的な辞書には載っておらず、読者も使用しません。

悪い点：ステージングは大規模なコンテンツ変更のリスクを軽減する。

利点：ステージング環境を使用すれば、大規模なコンテンツ変更を本番環境に公開する前に確認することができます。

一般的なビジネス用語で問題ありませんし、それが目的ではありません。 Leverage、 robust、 unblock、および exemplar はすべて通常の英語として読み上げられます。

比喩表現

何が起こっているのかを説明してください。比喩ではなく。読者が「それは実際には何をするの？」と疑問に思うような場合、その比喩は本来伝えられない意味を帯びていることになる。

問題点：CKEditor 4 のハンドラがエディタのツールバーを消去してしまう。

良い点：CKEditor 4 のハンドラが CKEditor 5 が解釈できないツールバーを返すため、エディタはボタンなしでレンダリングされます。

悪い点: トランスフォーマーの中核は、 style.definitions に追加するエントリです。

良好: トランスフォーマーは style.definitions にエントリを 1 つ追加します。

結果を隠す動詞

動詞が動作を表す場合は、その動作によって何が生じるかを述べなさい。はを正規化し、 はを処理し、 は を処理する、といった単語は、読者にその結果を伝えずにアクティビティに名前を付けます。裸の は を返しますが、オブジェクトに情報があるため、同じ問題が発生します。

悪い点: existingItems 変数はツールバー構成を正規化します。

良い点: existingItems 変数には、構成が配列かオブジェクトかに関わらず、ツールバーのアイテム名が格納されます。

悪い例：この分岐はツールバーを置き換えて戻ります。

良い点：この分岐はツールバーを置き換え、変更された設定を返します。

名詞スタック

名詞が積み重なった場合、最も右にある修飾語が中心となる名詞に最も強く結びつく。エディタサンプルアプリケーション は「エディタサンプル」とアプリケーションとしてグループ化され、エディタが生成したサンプルとして読み取られます。名詞の分類を表す語を一番外側に配置し、3つの名詞が重なった場合は分割することを推奨します。

悪い例：Liferayのエディタサンプルアプリケーションの1つ

良い例：Liferayのサンプルエディタアプリケーションのいずれか または Liferayのエディタ用サンプルアプリケーションのいずれか

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

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

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

もし/ならば

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

動詞構文

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

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

主題と参照に関する合意

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

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

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

不明確な指示対象

単語が指すものが明白で近くにある場合を除き、 it、 this、 that、または here を使用しないでください。

悪い点：従来、開発者はすべてを手作業で構築していた。

良い点：従来、開発者はフォーム、検証、および永続化レイヤーを手作業で構築していました。

関連する2つの習慣。（これは を必要とする）または （これは を必要とする）を、曖昧な （これはを意味する）よりも優先します。そして、 ここ は読者が見ることができる場所である必要があるため、共有画面のないページでは「インターフェースのこの場所」を避けてください。

普遍的な組織原理

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

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

読者が達成しようとしていることを中心にコンテンツをグループ化し、それをサポートする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 は製品なので、表の最後の行に示されているように、 Liferay Portalの代わりにこれを記述します。単語 Portal は、ソースリポジトリ名 (liferay-portal 用に予約されています。読者向けの文章には使用しないでください。

コード名とUI名

Liferay DXPエンティティの中には、インターフェースに表示される名前と、コードで使用される名前が異なるものがいくつか存在する。エンティティを説明する際は、UI名を使用してください。コードネームが正しい箇所は以下のとおりです。

• コードエンティティ: 記事の読者層に関わらず、Java サービス、データベース テーブル、ポータル プロパティ、ポートレット クラスなど、コードエンティティ自体についての文。
• UI ラベル: それを含むラベル、例えば ポートレット モード。ラベルを正確に再現してください。

コードネーム	UI名
デポ	アセットライブラリ、デザインライブラリ、プロジェクト、スペース
expando	カスタムフィールド
レイアウト	ページ
ポートレット	ウィジェット

ヘッドレス API コンテンツでは、両方の代わりに SitePage や WidgetInstanceなど、API 独自のスキーマ名を使用します。

文章中では、これらのUI名は普通名詞であり、大文字は使用しません。 UI要素ラベルとして大文字にするのは1文字のみです。 UI要素 に従ってください。

良い: アセットライブラリ アプリケーションを開き、アセットライブラリを作成します。

これらのコードネームにはより注意が必要です。

• Depot は 4 つの UI エンティティの名前を記述します。リーダーが作成または開くものを記述してください。
• レイアウト はコード内のページのみを意味します。また、ページの領域の配置を示す UI ラベルでもあり、例えば レイアウト テンプレートや、オブジェクトでは入力フォームの配置に オブジェクト レイアウト を使用します。のレイアウト をその意味で維持してください。
• ポートレット は、ユーザーがページ上に配置できる場合にのみウィジェットを意味します。これは開発者向けコンテンツにも当てはまります。なぜなら、読者はポートレットをデプロイし、ウィジェットを配置するからです。ユーザーが配置できないポートレット（アプリケーションの管理ポートレットなど）には、アプリケーションのラベルで名前を付けます。 Web コンテンツ、 ジャーナルポートレット ではありません。

悪い例：ページにポートレットを追加する。

良い点：ページにウィジェットを追加する。

良い: LayoutLocalService はレイアウトを作成して返します。

最後の例は、Javaサービスが何をするかを開発者向けコンテンツで説明しているので、コード名はそこにふさわしい。

展開フィールド は展開行の例外です。カスタムフィールドアプリケーションで追加されたフィールドとオブジェクトフィールドを区別する必要がある箇所にのみ記述し、最初に使用する際に定義してください。

ルールの適用範囲

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

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

インストラクター主導型トレーニング

講師主導型トレーニングは、3つ目のコンテンツタイプです。その完全な規格は、このガイドではなくトレーニング資料に記載されています。なぜなら、そのほとんどはスライドと講義資料に関するものだからです。トークトラックはスピーチなので、教室ではいくつかのルールが逆転します。

ルール	ドキュメントとコース	インストラクター主導のトレーニング
未来形	アクセスが拒否されています	先を指し示すために必要です（「明日は…に移動します」）。
収縮	勧められた	必須
「私たち」と「～しましょう」	避ける	予想通り、共有の旅
「単純に」そして「ただ」	なし	自然な話し方のリズムに合わせてリラックスしたが、真の難しさを軽視することはない
役割投影	アクセスが拒否されています	聴衆の役割を指摘するのは正しいが、感情やスキルを投影するのは正しくない。

このガイドのその他のすべてはトレーニングにも適用されます。オックスフォード・コンマ、用語表、すべての画像のaltテキスト、 は 必要であるのに対し は必要です。

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

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

フィードバック

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