こんにちは、 @kz_morita です。 社内のドキュメントについて色々と調べていたときに Diátaxis というフレームワークがあるのを知ったので紹介します。 Diátaxis について Diátaxis はテクニカルドキュメントのフレームワークです。 Diátaxis 以下の４つの構造からなります。 TUTORIALS HOW-TO GUIDES REFERENCE EXPLANATION TUTORIALS いわゆるチュートリアルです。 実際に手を動かして、学ぶコンテンツになります。 内容を詳細に説明するというよりは、説明したい対象を理解するために手を動かして学ぶ系のコンテンツです。 HOW-TO GUIDES ある特定の問題や、結果に向かっての手順などを示すものです。TUTORIALS が学習に重きをおいていたのに対し、HOW-TO GUIDES は目的指向です。 〇〇する方法といった形で、実現したい目標に対してどのように達成するかの手順を示します。 システムを使用するユーザー目線でのユースケースについて書かれます。 REFERENCE REFERENCE はシステムの技術的な説明と操作方法を記載します。 こちらは情報指向で、よくある API Reference などがこちらに当たります。 こちらが満たすべきこととしては、曖昧さがなく明確なことや、意見などを含まず中立的に書かれていることです。 EXPLANATION EXPLANATION は、システムの理解を深めるために記載されます。 システムについてより詳しく理解するために、談話的に書かれます。 ちなみに公式サイトには、 (one could say, explanation is the only kind of documentation that it might make sense to read in the bath) と書かれていて、お風呂の中で読むのに唯一価値があるものとありました。

こんにちは、 @kz_morita です。 先日行われた勉強会 でデザインドキュメントというソフトウェア開発時に各ドキュメントについて聞いて，興味が湧いたのでしらべてみました． デザインドキュメントとは デザインドキュメントは Google などの企業でソフトウェア開発を行う際に一緒に書かれるドキュメントのことです． ソフトウェアがどのような問題をどのように解決するのかを，ソフトウェアよりより高いレベルで伝えるための手段としてもちいられます． 何を書くべきか このドキュメントには，実装のアプローチや，主要な設計上の決定事項，考慮されたトレードオフなどが書かれます． 何を書くべきかという明確なルールはないためそれぞれのプロジェクトに合った形で改造していくのが良さそうです． 以下に自分が参考にした一例を載せます． - プロダクト開発・機能開発・改善の背景 - 課題は何か＝何を解決するのか - システムの技術的概要, アーキテクチャー図 - スコープ - プロジェクトの参加者 - 用語集 - 選定した解決手段について - 選定の根拠、トレードオフ - 詳細なアーキテクチャー図など - PoCの内容と結果 - 選定しなかった解決手段について - 手段の概要と、不採用の根拠 - 外部依存の概要 - 機能そのもの、解決手段についてセキュリティ観点からの考察 - 現時点で考えられるリスク - リスクの概要 - 考えられるリスクへの対応策 - 現時点で対応策を取らない理由 - テスト観点からの考察 - 運用観点からの考察 - 運用時の考慮事項 - 障害の発見と復旧手法 - References - etc...etc.. 特に重要なのは，考慮したけど採用しなかったものや，技術選定の際の選定基準やトレードオフ，またその技術を使うことで起こりうるリスクなどになるかなと思います． デザインドキュメントの価値 メリット ドキュメント化することにより，早い段階で設計のレビューを行ったり問題点を話し合うことで手戻りがすくなるほか，組織内での合意形成などにも役に立ちます． そして何より，考古学をしなくてよくなるということが最大のメリットに感じました． ここで考古学といったのは，例えば古いシステムの古い仕様について聞きたいときに，プロジェクトに当時在籍していた人がすでに退職してわからなかったりする場合には，コードやコミットログ，チャットのログなどから状況を推測する必要がある事象のことです．