Quarkus documentation concepts

トピックを説明することに重点を置いています。読者がコンセプトを理解できるよう支援することを目的としています。

指導、指示、参考情報の記載はしません。チュートリアル、ハウツー、リファレンスガイドなどを参照する必要がある場合は、それがある場所を示しますが、情報をコンセプトガイドに直接コピーすることはしません。

そのように動作する 理由 や、特定の方法でビルドされた 理由 を説明する背景情報やコンテキストを提供します。設計上の決定事項、歴史的な理由、技術的な制約などを引用して、自分の主張を再確認できます。

説明を明確にする具体的な例が含まれます。ただし、特定のテクノロジーや実装パターンに過度に依存する説明は避けます。

コンセプトを多角的に分析して他のコンセプトと比較し、読者が理解するために適切かつ有用であるか議論します。

説明しているコンセプトの長所と短所について、さまざまな潜在的なユースケースまたはアプリケーションと比較して意見を表明します。

タスクを完了する方法をガイド (手順) または実演します。

タスクを開始するのに十分なコンテキストがあると仮定します。

タスクを完了するために必要な手順を具体的に記述していますが、この手順はさらに大きなタスクの途中である可能性があります。

コンセプトの説明は他のドキュメント (コンセプトなど) に任せて省略します。

実際のユースケースに適応できます。

実用的 (完全ではない) です。

簡潔で、要点を押さえています。述べ、説明し、周知します。

他のリファレンスガイドと (可能な限り) 整合しています。テンプレートに従うと整合性が取りやすくなります。

自分のトピックを説明することに焦点を当てています。他のソースからのコンセプトを説明することはありません。

説明している内容を読者が理解できるように、例やイラストを提供します。

最新の状態に保たれています。設定リファレンス資料が作成されるとはいえ、設定の適用方法を説明するエクステンションリファレンスは正確かつ有用である必要があります。

読者に学習体験を提供し、できることを与えます。

読者が開始できるように促します (エキスパートを育成するものではありません)。

読者が従う必要があり、わかりやすい結果をもたらす、具体的な手順を提供します。

信頼性が高く、一貫性があります (常にすべてのユーザーに適用できる)。

タスクを完了するための十分な情報のみ含まれます。追加のコンテクストの提供については、他のタプのドキュメント (コンセプトやリファレンス) に委ねます。

タスクを実行するための 1 つの方法に焦点を当てます。それ以外の方法は、他のタイプのドキュメント (例: ハウツーガイド) で説明しています。