Liferayの高レベルスタイル

ドキュメントには 5 つの種類があります。

1. 概要: 概要は、セクションの最上部に階層的に配置され、機能が読者にどのように役立つかを要約した高レベルの説明です。 現実世界の問題を解決するユースケースに重点を置いています。 また、このセクションの残りの部分では、機能を最適に使用できるようにする方法についても読者に説明します。

2. 概念: トピックについて、個々の機能や概要以外の詳細な説明が必要な場合は、概念ドキュメントがそのギャップを埋めます。 これは、機能がどのように動作するかを示す機能ドキュメントの前、または、より一般的には、機能の説明の後に、機能で使用できるすべてのオプションを示すために配置できます。 前者の例としては、 コレクション ページが挙げられます。後者の例として、利用可能なすべての ワークフロー ノードの説明が挙げられます。

3. 機能: すべてのドキュメントの基礎として、各機能とその動作について説明します。 機能ドキュメントでは、段落と説明を最小限に抑えて、—番号付きの手順を使用して—読者が Liferay のすべての機能を使用する方法を説明します。 機能ドキュメントは、ユーザー中心または開発者中心にすることができます。 Liferay のドキュメントは常に機能が完全である必要があります。以下のタイプでは、機能ドキュメントを基礎および参照として使用します。

4. シリーズ: トレーニング コース、学習パス、ソリューション (下記参照) に使用され、ユース ケースに対する具体的なソリューションの作成を読者にガイドします。 各シリーズのセクションは、そのセクションで何を構築するか、どのように—高レベルで—構築するかを説明する導入とスクリーンショットで始まり、 さあ、始めましょう！でまとめられます。 ボタンを押して手順を開始します。 セクションの残りの部分には、Liferay でのユースケースの解決方法を読者に案内する番号付きの手順が主に記されたドキュメントが含まれています。 手順ドキュメントには具体的な手順のみが示されており、使用される機能の説明は最小限で、代わりに読者が詳細を知りたい場合に備えて、それらの機能を説明する機能ドキュメントへのリンクが含まれています。 可能であれば、シリーズには、読者の Liferay インスタンスにインポートまたは展開するために、シリーズで作成された内容を表すダウンロード可能なアセットへのリンクが常に含まれます。

5. ソリューション: 特別なタイプのシリーズであるソリューションドキュメントでは、Liferay サイト初期化子として実装された本格的な Liferay ソリューションについて説明します。 読者がソリューションを最初から再構築するために実行できる手順にソリューションを分解します。 これは、Liferay 実装のベスト プラクティスについて読者に説明し、読者が従うことができる Liferay インスタンスにすでに展開されている具体的な例を提供します。

ドキュメンテーション音声

私たちは、Liferay のドキュメントの表現を統一するために多大な努力を払っています。 多くのライターが 1 人のライターのように見えるように、Liferay のテクニカル ライターは、一連の標準と編集プロセスに従って、どのライターが記事を書いたかに関係なく、読者が記事ごとに同じ文体に遭遇できるようにします。 この音声の高レベルの特徴は、フレンドリーでカジュアルであることです。 それ以外にも、私たちは『 スタイルの要素 』の第 1 章と第 2 章に記載されているルールを守り、特に「 不要な単語を省略する」というルールを重視します。

フレンドリー

散文は親しみやすく、歓迎的な内容であるべきです。 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 をクラスタ環境で動作するように構成するために必要な内容を文書化し、独自の Docker コンテナ以外のアプリケーション サーバー構成については文書化を避けています。

カジュアル

ドキュメントは、英語が母国語でない人でも理解しやすいようにカジュアルなスタイルで書かれています。 私たちは形式ばった表現や不必要な長い言葉を避けます。 単語数を減らして文章の流れを良くするために、短縮形の使用が推奨されます。

段落ではなくステップ

可能な限り、手順に関する事項を段落で説明するのではなく、番号付きのステップに分割します。 情報は段落内に埋もれている場合があり、番号付きリストの一部として表示されると見つけやすくなります。 さらに、お客様が手順を実行するのに問題がある場合は、問題が発生した正確な手順番号を提供していただければ、Liferay サポートにとって役立ちます。

不要な言葉を省く

ウィリアム・ストランクの有名なルール、「 不要な言葉を省略する」は、私たちのマントラです。 Liferay テクニカル ライターは、 スタイルの要素 の第 1 章と第 2 章を学習し、すべてのルールに従う必要がありますが、最も重要なのは、次の 1 つに留意することです。 このドキュメントの付録には、文章を簡潔にするために短縮したり削除したりできる、よく使用されるフレーズのリストがあります。

明らかに、ストランクとホワイトのルールは特にテクニカル ライターに向けたものではなく、あらゆるスタイルで執筆する際に彼らの経験から学ぶとよいすべてのライターに向けたものです。 Liferay の技術ドキュメントに関する特定の標準 (以下) は、 スタイルの要素の基礎に基づいています。