Liferayスタイルガイド

Liferay スタイルガイド は、—巨人の肩の上に成り立っています。具体的には、 シカゴ マニュアル オブ スタイル とストランクとホワイトの スタイルの要素 の巨人の肩の上に成り立っています。 このガイドに明記されていない箇所については、そこに書かれている内容を前提としてください。 これら2つのスタイルガイドは、本書の基礎となるものであり、実際、これらがなければ本書は存在し得なかったでしょう。

Liferayのドキュメントスタイルは、以下の4つの包括的な価値観に基づいています。

1. ドキュメントは 包括的です。ソフトウェアについて知っておくべきすべての情報が記載されています。

2. ドキュメントは 簡潔です: 要点を押さえており、無駄な記述はありません。

3. ドキュメントは 一貫性があります: 個々のドキュメントは全体的なメッセージに関連しています。

4. ドキュメントは 明瞭性を備えています。つまり、できるだけ多くの人にメッセージが明確に伝わるように書かれています。

包括的なドキュメント

Liferayのドキュメントは、どのような概念が利用可能で、それらをどのように操作すればよいかがわかるように構成されています。 ユーザーは、特定のトピックを検索するのと同じくらい簡単に、そのトピックを閲覧できるべきである。 私たちは、目標達成に対応する形で組織化することでこれを実現します。 ドキュメントには複数の階層があります。 基盤となるのは、Liferay ソフトウェアが提供するすべての機能を説明する 機能 ドキュメントです。 土台の上には、 概念的な ドキュメントがあります。 本書は、よく練られた導入文で構成されており、機能の使用方法を説明することで、機能に関するドキュメントをさらに発展させたものとなっている。

簡潔なドキュメント

私たちはLiferayのドキュメントを簡潔にするために努力しています 。 段落を短くし、可能な限り箇条書きを用い、長々とした説明を避けることで、主題から逸れることなく文章を書くことができます。 私たちの目標は、内容をできる限り分かりやすくすることです。 私たちは、これを実現するために、簡潔で分かりやすい説明、図、イラスト、さらには動画なども活用しています。

一貫性のあるドキュメント

Liferayのドキュメントは、このドキュメントで定義されている特定のスタイルで記述されています。 Liferayのスタイルをうまく踏襲することで、多くのライターが統一された文体で執筆できるようになる。 Liferayのドキュメントを読めば読むほど、私たちがどのように情報を提示しているかが分かってきます。そして、この一貫したスタイルのおかげで、次に何が起こるかが予測できるため、学習が容易になります。

明確なドキュメント

効果的な文書化のためには、明確でなければならない。 私たちは、発信するメッセージと受け取るメッセージが同等になるよう尽力しており、そのための方法はこれらの基準に概説されています。

さらに、このドキュメントにはただ一つの目的があります。それは、Liferayの概念をできる限り効果的に教えることです。 ドキュメント全体を通して一貫した例と使用例を用いることで、ドキュメント全体が一体感のあるものとなるようにしています。 さまざまなスタイル（概要、概念、機能、リファレンス）で作成されたドキュメントは、学習者に応じて異なる方法でLiferayの機能を伝えることで、互いに補完し合っています。

あなた

上記で説明したさまざまな種類のドキュメントを定義するために費やした努力、コミュニケーションを明確にするための後述する標準規格、そしてLiferayのスタイルが確実に遵守されるようにするためのワークフローなど、あらゆる努力にもかかわらず、皆様のご協力なしには、私たちの取り組みが成功しているかどうかを知ることはできません。 ここで説明する基準は、長年にわたるコンテンツの定義、テスト、改良の結果ですが、人間は完璧ではないため、改善の余地は確かにあります。 これらの基準のいずれかが原因で不明瞭な点や納得できない点がある場合は、 Liferay Discuss を通じてフィードバックをお送りください。

ルールプライオリティー

すべての規則が同じ重みを持つわけではない。 これらのガイドラインを適用する際は、人間が執筆する場合でも、自動化ツールを使用する場合でも、以下の優先順位を使用してください。

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

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

ルールの適用範囲

このガイドに記載されているルールのほとんどは、概要、概念、機能、リファレンスなど、すべてのドキュメントタイプに適用されます。 以下の規則は適用範囲を狭めています。

• 「私たち」や「～しましょう」は使用しません: すべての読者向けドキュメントに適用されます。 このスタイルガイドなどのメタドキュメントでは、Liferay という組織を代表して発言する場合、 私たち を使用することがあります。
• 名前付きUI要素ラベル： ラベルに本来禁止されている単語が含まれている場合でも、インターフェースに表示されているとおりに正確に再現します。 これはすべての文書タイプに適用されます。

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

規則が矛盾しているように見える場合は、以下の解決策を適用してください。

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