Liferayスタイルガイド
Liferay スタイル ガイド は、巨人—の肩の上に成り立っています。具体的には、巨人である シカゴ マニュアル スタイル と、Strunk と White の スタイルの要素です。 このガイドに記載がない場合は、そこに書かれている内容を想定してください。 これら 2 つのスタイル ガイドは、ここに記載された内容の基礎となるものであり、実際、これらがなければこのガイドは実現できません。
Liferay のドキュメント スタイルは、次の 4 つの包括的な価値観に基づいています。
-
ドキュメントは 包括的です。ソフトウェアについて知っておく必要のあるすべての情報が表示されます。
-
ドキュメントは 簡潔です。要点を押さえ、無駄な情報を避けています。
-
ドキュメントは まとまりがあります: 個々のドキュメントは全体的なメッセージに関連しています。
-
ドキュメントには 明確さがあります。つまり、できるだけ多くの人にメッセージが明確に伝わるように書かれています。
包括的なドキュメント
Liferay のドキュメントは、利用可能な概念とその操作方法を示すように構成されています。 特定のトピックを検索するのと同じくらい簡単に、そのトピックを閲覧できる必要があります。 解決目標に対応する方法で整理することでこれを実現します。 ドキュメントには複数の層があります。 基礎となるのは、Liferay のソフトウェアが提供するすべての機能を説明する 機能 ドキュメントです。 基盤の上には 概念的な ドキュメントがあります。 適切に設計された導入テキストで構成され、機能の使用方法を説明することで機能のドキュメントを構築します。
ソリューションとコースは、Liferay ソフトウェアの完全な実装を説明することで、機能と概念のドキュメントを補完します。 ソリューション ドキュメントでは、Raylife 保険アプリケーションや Minium コマース実装など、Liferay の特定のアプリケーションを作成する手順を説明します。 コースでは、サーバーのプロビジョニングからサイト トラフィックの分析まで、本番サイトに Liferay を実装するための包括的な構成要素を学習します。
このようにして、Liferay は、自分のニーズに合わせて Liferay を使用したり評価したりしたいすべての人の学習ニーズを満たすことができます。
簡潔なドキュメント
私たちは、Liferay のドキュメントを 簡潔にするために一生懸命取り組んでいます。 段落を短くし、可能な場合は箇条書きを使用し、長い説明を避けることで、主題を押さえることができます。 私たちの目標は、コンテンツをできるだけ簡単に理解できるようにすることです。 これを実現するために、短くてわかりやすい説明、図、イラスト、さらにはビデオを使用します。
統合ドキュメント
Liferay のドキュメントは、このドキュメントで定義された特定のスタイルで書かれています。 Liferay スタイルに従うことで、多くのライターの意見が 1 つになります。 Liferay のドキュメントを読めば読むほど、情報がどのように提示されるかが理解できるようになります。また、この一貫したスタイルにより、何を期待すべきかがわかるため、学習が容易になります。
明確なドキュメント
効果を上げるには、ドキュメントが明確でなければなりません。 私たちは、伝えられるメッセージと受け取られるメッセージが等しくなるように努力しており、そのための方法がこれらの標準に概説されています。
さらに、このドキュメントの目標はただ一つ、Liferay の概念をできるだけ効果的に教えることです。 ドキュメント全体が 1 つにまとまるように、ドキュメント全体で一貫した例とユース ケースを使用します。 さまざまなスタイル (機能、概念、ソリューション、コース) のドキュメントは、さまざまな学習者にさまざまな方法で Liferay の機能を伝えることで、互いに補完し合います。
あなた
上で説明したさまざまな種類のドキュメント、コミュニケーションを明確にするための下記の標準、Liferay スタイルに準拠するためのワークフローを定義するために私たちが費やしたすべての努力にもかかわらず、皆さんなしでは私たちが成功しているかどうかは決してわかりません。 ここで説明する標準は、長年にわたるコンテンツの定義、テスト、改良の結果ですが、完璧な人間は存在しないため、改善できる方法は必ずあります。 これらの標準のいずれかに関して不明な点や納得できない点がある場合は、 Liferay の Ask アプリケーションを通じてフィードバックをお送りいただくようお願いいたします。