はじめに
こんにちは。 KDDIアジャイル開発センターの小板橋です。 この記事は、KDDI Engineer&Designer Advent Calendar 2021の17日目の記事です。
今回は、Diataxisという技術文書作成のための体系的なフレームワークについてまとめていこうと思います。
Diataxisというフレームワーク
少し前に、Ubuntuの支援及び開発援助を行うCanonical社から「今後CanonicalでのドキュメンテーションはDiataxisフレームワークを用います」という宣言が発表されました。(https://gihyo.jp/admin/clip/01/ubuntu-topics/202111/19)
- Diataxisを要約すると、ドキュメントと名の付くものは全てTutorial、How-to Guide、Technical Reference、Explanation の4つに分類し、それぞれがどのように記述されるべきかを整理する思考フレームワークです。
Tutorials
- Tutorialsは、初心者が最初に始める知識習得のための起点です。
- 目的は、初心者が始められるようにするために教育し、リードします。
- なので、形式としてはレッスンするに近いです。
How-to guides
- How-to guidesは、特定のタスクを解決する方法を教えます。
- なので、一連のステップとして、ガイド、デモンストレーションに近いです。
Reference
- Referenceとは、参考資料や定義や動作を示すものです。
- Explanationsと被ると思いますが、こちらは技術情報に関して、"~とは…？"を教えるものです。
Explanations
- Explanationsは、解説や理解のための詳細なドキュメントです。
- Referenceとの違いは、こちらは技術情報に関しての"なぜ…？"を教えるものです。
まとめ
- Diataxisにより、明確にドキュメントが区分されることで、ドキュメントの対象となる技術や製品をより使いやすくすることができると思います。Canonical社が導入したことで、今後、これに基づいた整理が行われることで、Ubuntuの「使いやすさ」に影響がでるのではないかと期待できそうです。