Diátaxis

Diátaxis¶ 技術文書作成のための体系的なアプローチ。 Diátaxisは、文書作成について考え、実行する方法です。文書作成ユーザーのニーズを体系的に理解することから生まれる、コンテンツ、アーキテクチャ、形式へのアプローチを規定します。 Diátaxisは、4つの異なるニーズと、それに対応する4つの文書形式（チュートリアル、ハウツーガイド、テクニカルリファレンス、解説）を特定します。これらを体系的な関係の中に配置し、文書自体もこれらのニーズの構造を中心に構成されるべきだと提案します。 Diátaxisは、文書コンテンツ（何を書くか）、スタイル（どう書くか）、アーキテクチャ（どう構成するか）に関連する問題を解決します。 文書のユーザーに役立つだけでなく、Diátaxisは文書作成者や保守担当者にとっても価値があります。軽量で理解しやすく、適用も簡単です。実装上の制約を課しません。文書に品質の能動的な原則をもたらし、保守担当者が自身の作業について効果的に考えるのに役立ちます。 目次¶ Diátaxisを始める最善の方法は、簡単な入門書を読んだ後に適用することです。 ここから始める これらのページは、このアプローチを即座に、具体的なものにするのに役立ちます。 Diátaxisの適用 チュートリアル ハウツーガイド リファレンス 解説 コンパス ワークフロー このセクションでは、Diátaxisの理論と原則をより深く掘り下げ、その根底にあるニーズの理解を提示します。 Diátaxisの理解 基礎 マップ 品質 チュートリアルとハウツーガイド リファレンスと解説 複雑な階層 Diátaxisは実践で証明されています。その原則は、数百の文書プロジェクトで成功裏に採用されています。 Diátaxisにより、ユーザーが愛し、貢献者が追加することを愛する、高品質な内部文書セットを構築することができました。 — Greg Frileux, Vonage Gatsbyでは最近、オープンソースの文書を再編成しましたが、Diátaxisフレームワークはそのプロジェクト全体で私たちの頼れるリソースでした。4つの象限は、各タイプの文書に対するユーザーの目標を優先するのに役立ちました。Diátaxisフレームワークを中心に文書を再構築することで、ユーザーが必要なリソースを必要な時に見つけやすくなりました。 — Megan Sullivan Cloudflareの開発者向けドキュメントを再設計する際、Diátaxisは情報アーキテクチャの北極星となりました。新しいコンテンツをどこに配置すべきか分からないときは、フレームワークを参照しました。私たちの文書は、読者にとっても貢献者にとっても、これまで以上に明確になりました。 — Adam Schwartz