Diátaxis:技術文書の体系的フレームワーク

原題: Diátaxis

なぜ重要か

オープンソースや大企業のドキュメント設計標準として普及が進んでおり、ソフトウェア品質向上の重要な土台となりつつある。

Diátaxisは、技術ドキュメント作成のための体系的なフレームワークで、Daniele Procidaが提唱した。チュートリアル・ハウツーガイド・テクニカルリファレンス・説明という4種類の形式を定義し、ユーザーニーズに基づいた文書構造化を促進する。Vonage、Gatsby、Cloudflareなど数百のプロジェクトで採用実績がある。

Diátaxisは、古代ギリシャ語の「dia(横断)」と「taxis(配置)」に由来するドキュメント設計のフレームワークである。Daniele Procidaによって提唱され、技術文書のコンテンツ(何を書くか)、スタイル(どう書くか)、アーキテクチャ(どう整理するか)に関する課題を解決することを目的としている。

フレームワークの核心は、ドキュメントを4種類に分類することにある。①チュートリアル:学習者向けの実践的な学習コンテンツ、②ハウツーガイド:特定の目標を達成するための手順書、③テクニカルリファレンス:情報を検索・参照するための技術仕様文書、④説明(Explanation):概念や背景を理解するための解説文書、の4つである。それぞれをユーザーのニーズに対応させて整理することで、読者が必要なときに必要な情報を見つけやすくする。

Diátaxisは実装上の制約を課さず、軽量で導入しやすい点が特徴とされている。実際に数百のドキュメントプロジェクトで採用されており、VonageのGreg Frileux氏は「ユーザーと貢献者の両方が高品質な内部ドキュメントを構築・追加できるようになった」とコメント。GatsbyのMegan Sullivan氏は、オープンソースドキュメントの再編成にDiátaxisを活用し、ユーザーが必要なリソースを発見しやすくなったと述べている。CloudflareのAdam Schwartz氏は、開発者向けドキュメントの設計においてDiátaxisを情報アーキテクチャの指針として採用したと説明している。

出典

diataxis.fr — 元記事を読む →