Liferayのフレーズ
Liferay のスタイルでは、散文を特定の方法で表現します。 これらも慣習であり、正しいとか間違っているということではありません。これらは、包括的、簡潔、まとまりのあるコミュニケーションという目標に基づいて私たちが選択した方法です。
オックスフォードコンマ
オックスフォードコンマ（またはシリアルコンマ）は連続して使用されます。 3 つ以上の項目をリストする場合は、最後の項目の接続詞の前にコンマを入れる必要があります。 次の例に示すように、コンマを省略すると、明確さが失われる可能性があります。
I want to thank my mentors, my parents and the President for their help.
あなたの指導者は本当にあなたの両親と大統領ですか? それとも、本当にこう言いたかったのでしょうか:
I want to thank my mentors, my parents, and the President for their help.
オックスフォードコンマにより文が明確になります。
未来時制
ドキュメントでは未来形を使用しないでください。 何かを説明するためにそれが必要になる可能性はほとんどありません。
このアクションにより、データベースに新しいレコードが作成されます。
この文では、未来形を使う必要がないのに未来形が使われています。 代わりに、現在形を使用します。
このアクションにより、データベースに新しいレコードが作成されます。
しなければならない
必ず は同等のものより常に短くなります。
アセットを使用するには、アセット レンダラーとアセット レンダラー ファクトリーが必要です。
1 つの単語は 2 つの単語より優れています。また、 need to は 2 つの単語で、 must は 1 つの単語だけなので、これをすべてのケースで must に変更します。
アセットを使用するには、アセット レンダラーとアセット レンダラー ファクトリーが必要です。
シンプルかつ公正
という単語は、単に や という単語は、決して使用しないでください。 あなたにとって簡単そうに見えるものも、初心者にとっては簡単ではありません。 単に は、テキスト内の省略できる余分な単語です。 の場合も同様に、となります。
ぶら下がり分詞
次の手順に従ってください。
これはぶら下がり分詞です。 とそれに続くに目的語がないからです。 代わりに、次のようなフレーズを使用してください。
- 次の手順を実行します：
- 次のことを行います。
ほとんどの場合、次の よりも優れた構成が存在します。
主語と代名詞の一致
ユーザーがこの機能を実行すると、フィードバックが得られます。
ユーザー は単数形です; 彼ら は複数形です。 英語ではこれは間違いですが、一般的になりつつあります。 ほとんどの場合、これを解決する簡単な方法があります。 全体を複数形にします。
ユーザーがこの機能を実行すると、フィードバックが得られます。
コロン
コロンは独立節の後にのみ使用します。 次の用法は誤りです。
- アクセラレータを使用するには:
- サイトを作成するには:
- 以下に例を示します。
上記の例では、コロンの代わりにコンマを使用します。
メタ情報
メタ情報やドキュメントに関する情報は使用しないでください。 たとえば、次のようなことは決して言わないでください。
- この記事は
- この一連のチュートリアルでは、
- ライフレイでは、
これらはすべて埋め草であり、不必要です。 代名詞は厳密に あなた に限定し、記事、そのセクション、またはその形式については言及しないでください。
クロスリンク
ある記事から別の記事にリンクする場合は、リンクであっても上記のルール（メタ情報を避ける）に留意してください。 たとえば、これは悪いリンクです:
詳細については、 この記事を参照してください。
これは良いリンクです:
詳細については、「 フレンドリー URL」を参照してください。
数字を含める
シカゴマニュアルスタイルに従って、文中で数字に言及する場合、10 以下の場合は数字を書きます (例: 6 つのオプションがあります。）。 数字が10以上の場合は、数字（例： 16進数には16桁あります。）を使用します。）。
一覧
選択肢がたくさんあると言って選択肢をリストする場合は、番号付きリストを使用します。 リスト項目の数を指定しない場合は箇条書きを使用します。
例1：
サイトを作成するには、次の 3 つの方法があります。
- サイトを作成します。
- 組織を作成し、その組織のサイトを作成します。
- 新しいポータル インスタンスを作成し、サイトを作成します。
例2：
ボタンをクリックすると、次のオプションが表示されます。
- 表示
- 編集する
- 削除
決して役割を投影しない
私たちは読者の背景を決して知りません。 個人の場合もあれば、組織内の場合もあります。 これらの構造内の役割は異なり、ワークフローも異なります。 二人称代名詞 あなた (または「理解しました」) で十分な場合は、決して読者に役割、肩書き、または職務内容を投影しないでください。 たとえば、次のようなことは絶対にしないでください。
- 管理者はディレクトリ…を作成できます
- マーケターはフラグメントを使用して…
- 開発者は…のクラスを作成する必要があります
代わりに、次のようにします。
- フォルダを作成する
- フラグメントを使用することができます
- クラスを作成する
これを行うと、不要な単語も省略されることに注意してください。
読者に語りかける
教室では、先生がいて全員が一緒に学んでいるので、「 私たちは 特定のトピックに取り組んでいます」と言っても大丈夫です。 ドキュメントでは、読者に対して 私たちと呼びかけないでください。 一貫性を保ち、常に youを使用してください。
同様に、「～しましょう」とは言わないでください。
ソフトウェアは制御できない
ソフトウェアが決定を下したり、ソフトウェアがユーザーを制御しているように見えるような言い方をしないでください。 常にユーザーに権限を与えます。 たとえば、次のようには言わないでください。
- この機能により、
- ダイアログがポップアップ表示され、
代わりに、ソフトウェアではなくユーザーが制御できるようにします。
- あなたはできる
- ダイアログを使用して設定します
用語
用語の一貫性を保つのは難しいので、用語の使用方法に不一致が見つかった場合は修正する必要があります。 文書内に用語が見つかり、自分やスペルチェッカーが疑問に思う場合は、調べてください。
一般的な例
| 間違っている | 右揃え |
|---|---|
| バックエンド | バックエンド |
| フロントエンド | フロントエンド |
| Javascript（またはJSまたはjs） | JavaScript |
| サービスビルダー | サービスビルダー |
| RESTビルダー | RESTビルダー |
| オープンAPI | OpenAPI |
| インデックスの再作成 | 再インデクス |
| [ライフレイ_ホーム] | [Liferay Home] |
| 箱から出して | すぐに使える |
| フリーマーカーまたはフリーマーカー | FreeMarker |
| ドロップダウン | 落ちる |
任意
多くの場合、any という単語は削除できます。
使用しているテーマにスタイル ブックのトークン定義がない場合、ページ上の 任意の カラー ピッカー構成がカラー パレット構成に置き換えられます。
上記の文は、 の有無にかかわらずは同じ意味なので、削除できます。
動詞と副詞の組み合わせとその名詞
動詞副詞の名詞形には注意してください。 動詞副詞は 2 つの単語 (動詞と副詞) で構成され、名詞は 1 つの単語で構成されます。
| 動詞-副詞 | 名詞 |
|---|---|
| 分解する（どのように？） | 簡単に説明します |
| セットアップする（どのように？） | これはグラフィカルなセットアップルーチンです |
| ログインするには（どうやって？） | ログイン情報を決して漏らさないでください |
もし/ならば
BASIC プログラミング言語では、 if ステートメントには thenが必要です。 言語ではほとんどの場合そうではないので、 とを省略しても問題ありません。
動詞の構文
動詞の構造を崩さないように最善を尽くしてください。 例えば、
| オリジナル | 優先 |
|---|---|
| 異なるページを動的に表示する | 異なるページを動的に表示する |
| 最適に囲まれることができる | 最適に囲むことができる |
主語と指示対象
単数/複数の主語とその指示対象が一致していることを確認します。
誤り: 地理位置情報データベースには、IP アドレスとその発信国間のマッピングが含まれています。
正解: 地理位置情報データベースには、IP アドレスとその発信国間のマッピングが含まれています。