作ったツールの簡単なドキュメントを残したい

SaaS や PaaS を扱っているとプログラムを書く機会が少なってきますが、一方で意外と設定を出力したりする機能がなかったりするので、便利ツール的な位置付けでプログラムで作ることがたまにあります。 （半分は自己満足で作ります）

せっかくツールを作ったので、会社の人たちに使って欲しい気持ちがあり、README 的に簡単にマニュアルを残したいなと思っていたところ Design Doc という文章があることを知りました。

Design Doc の特徴

Design Doc とは、要は「仕様書」のようなもので、システムの目的や背景、アーキテクチャなどを書きます。
Microsoft や Google などの会社でも採用されているようです。
大きな特徴の1つはトレードオフが書かれていることで、 「なぜそのアーキテクチャにしたか」、「ほかに検討したアーキテクチャと不採用になった理由」が書かれています。

この点が個人的には面白いなと思いました。

通常の設計書では最終的に採用されたアーキテクチャしか書かれておらず、ほかに検討したアーキテクチャが文書として残りません。
プロジェクトの最中では資料として残っているかも知れませんが、プロジェクトが終わって運用フェーズに入ると闇の中です。
不採用になったアーキテクチャについて書くことでツールの理解も深まります。

前談が長くなりましたが、これを踏まえて作った便利ツールのドキュメントにはこれから列挙するものを盛り込むようにしました。書いていると心地よかったのでオススメです。
特にコンセプトは筆が進みます。

簡単に残せるドキュメントの目次

• はじめに
• 作成した背景・目的（解決したい課題や用途を書いてもOK）
• コンセプト/特徴（便利なところや推しポイント）
• 主な機能
• 環境準備
• 使い方
• フォルダ・ファイル構成
• 制約
• 検討した別の方法
• 参考

運用し始めたばかりなので、目次見直したら随時更新します。