Quarkusドキュメントのコンテンツタイプ
Quarkusのドキュメントは、コンセプト、ハウツー、チュートリアル、リファレンスの4つのコンテンツタイプに分類されています。Quarkusドキュメントの構成と構造は、技術文書オーサリングのためのDiátaxis体系的文書フレームワークに従っています。各コンテンツタイプは、異なるユーザーニーズを解決し、異なる目的を果たし、その作成に異なるアプローチを必要とします。
Diátaxis ドキュメントフレームワーク
QuarkusのドキュメントをDiátaxisドキュメンテーションフレームワーク[1]に合わせることにしました。これは、ドキュメントを参照するときにユーザーが持つさまざまなニーズに対応するコア コンテンツ構造を定義します。
Image credit: https://diataxis.fr/ The content types in the Diátaxis documentation framework[1]
以下は、文書の種類を簡単にまとめたものですが、この分類の理由をもっと理解したい方は、彼らのサイトを一読する価値があります。
コンセプトガイド (説明)
説明は、特定のトピックを明確にし、わかりやすくする ディスカッション です。説明は 理解を重視 しています。
優れたコンセプトガイド:
-
トピックを説明することに重点を置いています。読者がコンセプトを理解できるよう支援することを目的としています。
-
指導、指示、参考情報の記載はしません。チュートリアル、ハウツー、リファレンスガイドなどを参照する必要がある場合は、それがある場所を示しますが、情報をコンセプトガイドに直接コピーすることはしません。
-
そのように動作する 理由 や、特定の方法でビルドされた 理由 を説明する背景情報やコンテキストを提供します。設計上の決定事項、歴史的な理由、技術的な制約などを引用して、ポイントを再確認できます。
-
説明を明確にする具体的な例が含まれます。ただし、特定のテクノロジーや実装パターンに過度に依存する説明は避けます。
-
コンセプトを多角的に分析して他のコンセプトと比較し、読者が理解するために適切かつ有用であるか議論します。
-
説明しているコンセプトの長所と短所について、さまざまな潜在的なユースケースまたはアプリケーションと比較して意見を表明します。
ハウツーガイド
ハウツーガイドは、実際の問題を解決するために必要な手順を読者に 指示 します。ハウツーガイドは 目標を重視 しています。
優れたハウツーガイド:
-
タスクを完了する方法をガイド (手順) または実演します。
-
タスクを開始するのに十分なコンテキストがあると仮定します。
-
タスクを完了するために必要な手順を具体的に記述していますが、この手順はさらに大きなタスクの途中である可能性があります。
-
コンセプトの説明は他のドキュメント (コンセプトなど) に任せて省略します。
-
実際のユースケースに適応できます。
-
実用的 (完全ではない) です。
リファレンスガイド
リファレンスガイドは、機械や操作方法などの 技術的な説明 です。参考資料は、 情報を重視 しています。
優れたリファレンスガイド:
-
簡潔で、要点を押さえています。述べ、説明し、周知します。
-
他のリファレンスガイドと (可能な限り) 整合しています。テンプレートに従うと整合性が取りやすくなります。
-
自分のトピックを説明することに焦点を当てています。他のソースからのコンセプトを説明することはありません。
-
説明している内容を読者が理解できるように、例やイラストを提供します。
-
最新の状態に保たれています。設定リファレンス資料が作成されるとはいえ、設定の適用方法を説明するエクステンションリファレンスは正確かつ有用である必要があります。
チュートリアル
チュートリアルは、読者に、あるプロジェクトを完了するための一連の手順を示します。チュートリアルは 学習を重視 しています。
優れたチュートリアル:
-
読者に学習体験を提供し、できることを与えます。
-
読者が開始できるように促します (エキスパートを育成するものではありません)。
-
読者が従う必要があり、わかりやすい結果をもたらす、具体的な手順を提供します。
-
信頼性が高く、一貫性があります (常にすべてのユーザーに適用できる)。
-
タスクを完了するための十分な情報のみ含まれます。追加のコンテクストの提供については、他のタプのドキュメント (コンセプトやリファレンス) に委ねます。
-
タスクを実行するための 1 つの方法に焦点を当てます。それ以外の方法は、他のタイプのドキュメント (例: ハウツーガイド) で説明しています。
