ドキュメントと名のつくもののフレームワーク

https://gyazo.com/3c6630dd5f21f4bf66aa7ef8c689a863

Diátaxisフレームワークは、技術文書の構造の問題を解決することを目的としています。これは、製品との対話のサイクルにおけるドキュメントユーザーのニーズを理解するための体系的なアプローチを採用しています。

フレームワークは、チュートリアル、ハウツーガイド、テクニカルリファレンス、および 説明の4つのドキュメントモードを識別します。

これらの各モード（またはタイプ）は、さまざまなユーザーのニーズに対応し、さまざまな目的を果たし、その作成にはさまざまなアプローチを必要とします。

技術文書は、これら4つのタイプを中心に明示的に構成する必要があり、それらをすべて互いに分離して区別する必要があります。

言い換えれば、私たちがドキュメンテーションと呼ぶものは、基本的に1つではなく、4つです。これの意味と、これら4つの異なるものがどのように機能するかを理解することは、ほとんどのドキュメントの改善に役立ちます。

キュメンテーションを理論/実践と習得/応用の2つの知識軸に分割します。

https://gyazo.com/527bc91aee678cddb4a9a162b9ddb5bb

学習指向のフェーズ：私たちは学習から始めます。スキルを学ぶということは、それを実行するために真っ直ぐに飛び込むことを意味します。運が良ければ、教師の指導の下で。

タスク指向フェーズ：次に、スキルを機能させたいと思います。

情報指向のフェーズ：私たちの仕事が私たちの頭の中にまだ持っていない知識を必要とするやいなや、それは私たちがテクニカルリファレンスに相談することを要求します。

説明指向のフェーズ：最後に、作業から離れて、全体を理解するために私たちの実践と知識を振り返ります。

チュートリアルは、初心者が製品の基本的な能力を達成し、自分の目的で製品を使用できるようにするのに役立つ必要があります。チュートリアルは、初心者が製品の基本的な能力を達成し、自分の目的で製品を使用できるようにするのに役立つ必要があります。

学習者に学習体験を提供していない場合、チュートリアルは必要な仕事をしていません。

教師の義務

あなたの仕事は、学習者を専門家に変えることではなく、学習者を始めることです。

チュートリアルの言語

このチュートリアルでは、次のことを行います…

学習者が何を達成するかを説明します（注-「あなたは学ぶでしょう…」ではありません）。

まず、xを実行します。さて、yを実行します。yを実行したので、zを実行します。

あいまいさや疑いの余地はありません。

yを実行する前に常にxを実行する必要があります。理由は…（詳細については、説明を参照してください）。

可能な限り最も基本的な言語でアクションの最小限の説明を提供します。より詳細な説明へのリンク。

出力は次のようになります…

学習者に明確な期待を与えます。

注意してください…覚えておいてください…

学習者にたくさんの手がかりを与えて、彼らが正しい軌道に乗っていることを確認し、自分自身を方向付けるのを助けます。

安全な3層のhylomorphicstasisエンジンを構築しました…

学習者が達成したことを説明します（そして、穏やかな方法で賞賛します）（注-「あなたは学んだ…」ではありません）

ハウツーガイドは、実際の問題を解決するために必要な手順を読者に説明する指示です。ハウツーガイドは目標指向です。

ハウツーガイドは、チュートリアルとはまったく異なります

https://gyazo.com/9c769f02b11f9640e3bbcb5f187e124e

チュートリアルとは異なり、ストーリー全体の最初から始めて、読者を最後まで連れて行く必要はありません。ほとんどの場合、ユーザーも何かの真っ只中にいるでしょう。したがって、ユーザーが到達する方法を知っている出発点と、実際の質問に実際に答える結論を提供するだけで済みます。

問題を解決する

問題またはタスクは、ハウツーガイドの懸念事項です。その実用的な目標に固執します。追加されたもの（たとえば、不要な説明）は、ユーザーとユーザーの両方の気を散らし、ガイドの有用な力を弱めます。

命名に注意してください

ハウツーガイドが示していることを正確に表すタイトルを選択してください。

良い：アプリケーションのパフォーマンス監視を統合する方法

How to integrate application performance monitoring

悪い例：アプリケーションのパフォーマンス監視を統合する

Integrating application performance monitoring

（おそらく、このドキュメントは、実行する方法ではなく、実行する必要があるかどうかを判断する方法に関するものです）

非常に悪い：アプリケーションのパフォーマンス監視

Application performance monitoring

（多分それはについてですか-多分それはについてですが、どうか、またはだけでも説明何それはあります）

ハウツーガイドの言語

このガイドでは、その方法を説明します…

ガイドがユーザーに解決方法を示している問題またはタスクを明確に説明します。

xが必要な場合は、yを実行します。wを達成するには、zを実行します。

条件付き命令を使用します。

オプションの完全なリストについては、xリファレンスガイドを参照してください。

ユーザーがxに関連して行う可能性のあるすべてのことで、実用的なハウツーガイドを汚染しないでください。

リファレンスガイドは、機械の技術的な説明とその操作方法です。参考資料は情報指向です。

ソフトウェアの場合、リファレンスガイドでは、ソフトウェア自体（API、クラス、関数など）とその使用方法について説明しています。

おそらく、百科事典を調べて、成分について（たとえば、甘草について）読むことができます。

あなたが求めているのは情報です-正確で最新の包括的な情報です。あなたはその特性、その化学組成、それが他の成分とどのように相互作用するか、それが関連している他の成分や植物、それが持つかもしれない健康への影響について知りたいかもしれません。

https://gyazo.com/9c9529937fb60c1ce6dc3adcf91ff277

例：甘草はマメ科のマメ科の顕花植物です。または：甘草の過剰摂取は悪影響をもたらす可能性があります。

説明するだけです

テクニカルリファレンスには1つの仕事があります。それは、説明することと、それを明確に、正確に、そして包括的に行うことです。説明、話し合い、指示、推測など、他のことをすることはその仕事の邪魔になり、読者が必要な情報を見つけるのを難しくします。

説明は、特定のトピックを明確にし、明らかにする議論です。説明は 理解志向です。

良い説明を書く

接続する

説明を書くとき、あなたはあなたの読者のために理解の網を編むのを手伝っています。それが役立つ場合は、当面のトピック以外のものであっても、他のものとの接続を確立します。

コンテキストを提供する

説明の背景と背景を説明します。その理由を説明します。設計上の決定、歴史的な理由、技術的な制約など、影響を与え、具体的な例を挙げます。

主題について話す

説明ガイドがあるについて、彼らがしているという意味で話題を中心に、それ。説明ガイドの名前でさえ、これを反映している必要があります。あなたは、暗黙的（あるいは明示的に）配置することができるはず程度を各タイトルの前に。例：ユーザー認証について、またはデータベース接続ポリシーについて。

代替案や意見について話し合う

説明では、同じ質問に対する代替案、反例、または複数の異なるアプローチを検討できます。あなたは指示を与えたり事実を説明したりしていません-あなたは検討のためにトピックを開いています。説明を議論として考えることは助けになります：議論は反対意見を考慮し、比較検討することさえできます。

指示したり、技術的なリファレンスを提供したりしないでください

説明のリスクの1つは、他のものが忍び寄る傾向があることです。説明は、ドキュメントの他の部分が行わないことを行う必要があります。何かをする方法をユーザーに指示するための説明の場所ではありません。また、技術的な説明も提供しないでください。ドキュメントのこれらの機能は、他のセクションですでに処理されています。

説明の言語

xの理由は、歴史的に、y…

説明。

Wはzよりも優れています。なぜなら…

必要に応じて判断や意見を提供します。

システムyのxは、システムzのawに類似しています。しかし…

読者に役立つコンテキストを提供します。

一部のユーザーはwを好みます（zのため）。これは良いアプローチかもしれませんが…

代替案を検討します。

xは次のようにayと相互作用します：…

機械の内部の秘密を明らかにして、何かがそれが何をするのかを理解するのを助けます。