これは何?
長年保守しているソフトウェアの保守/開発を引き継いだのだが，背景やシステム全体を理解するのに苦労した。
そのため，自分は内部ドキュメントを積極的に作成すべきという思想を持っている。
だが，やみくもにドキュメントを書いてしまい，あちこちに情報が散らばってしまうとドキュメントが読まれない/更新されない/読み手を混乱させるという自体を招いてしまう。
本記事ではKent Bech氏の書籍Tidy First?にでてくるリファクタリングの考え方をドキュメント作成に応用することで，読者にドキュメント作成に前向きな気持ちになってもらうこと，よりよりドキュメントを書けるようになってもらうことの手助けができればと思っている。
そもそもドキュメントはいつ/どのくらい書くべきか?
この本を読む前の自分はエンジニア的な視点でしかリファクタリングを見れておらず，スパゲティコードを見つけたらすぐに修正したい衝動にかられていた。
しかし，Kent Beckはリファクタリングにコスト意識を持つこと，可能なら先にお金を稼いでそのお金でリファクタリングするほうが良いと述べている。
これはドキュメント作成においても同じであろう。
自分の場合はドキュメントを書く前に以下の2つを意識して，ドキュメントの粒度を決めるようにしている。
- 想定読者は誰か?
- 同様の作業を再度実施する可能性はどれくらいあるか?
- 自分が詰まったのはどこか?
また，リファクタリング同様，最低限振り替えりができるだけのメモは当日のうちに作ってしまい，整頓は時間のある時に行う形にすると良い
伝えたい内容に合わせて適切なドキュメントの種類を選ぶ
ざっくり以下のようにわけて最低限のテンプレ例を示す
- 仕様書: ※内部ドキュメントではあまり仕様書を書くことはないのでテンプレは本記事では割愛する
- 単発の手順書
- トラブルシューティング系
- 作業手順書
- オンボーディング資料
手順書
トラブルシューティング系
- どんな事象が起きたのか: エラー文などあるなら書いておくと検索しやすくなるのでgood
- トラブルが起きた原因: 不明な場合には予想でもよいので書いておく
- 解決方法
作業手順書
- なぜ、その作業を実施するのか、背景
- 事前準備: メンバーが共通で実施する環境構築手順以外でやることがあれば
- 作業の流れ: 以下は他の人も同じ轍を踏む可能性が高いのであれば書いておくことを推奨する
- 人に聞かないとわからなかったこと
- 勘違いしていたこと
- うまくいかなかったこと
オンボーディング系
以下を別々のドキュメントにわけて書いておくとよい
- どういうプロジェクトなのか: 使用言語、ライブラリ等
- 全体構成図など(あれば)
- 環境構築手順
- 最初に読むべきもののリンクなど
適切にドキュメントを配置する
※階層構造でドキュメントを配置する前提
自分は以下の順で評価してドキュメントをどこに配置するかを決めている
- 特定の案件、リリース等に関連して複数のドキュメントを作成した場合は案件名、リリースバージョンなどでまとめておく(※よく使用する手順などが追加された場合には、抜き出すなりリンクを張るなりして対応する)
- ドキュメントの種類でわける。
- よく使うものはなるべく上位に配置する
- 似た内容のものは同じディレクトリに集める
あくまでイメージだが、こういう感じ
オンボーディング資料
│ └── はじめに
│ └── 全体構成図
│ └── 環境構築
│ └── 最低限読むべきもののリンク集
│
手順書
└── トラブルシューティング系
├── トラブル1
├── トラブル2
└── 作業手順書
├── よくある作業1
├── よくある作業2
├── あんまり使わないやつまとめ
過去リリース
└── リリースA
├── 事前準備
├── 要件定義
├── ハマりポイント
├──実装メモ
読みやすいドキュメントにするための工夫例
目次の粒度をそろえる
意識するだけしか現状思いつかないので説明は割愛
主語と目的語を明確に書く
×認証失敗した際に認証失敗カウントを増やす
〇ユーザが認証失敗した際にMySQLのUserテーブルのfailed_cntを+1する
記載内容の要約を見出しにする
## 環境構築
### リポジトリのクローン
### ライブラリのインストール
意図や説明コメントをいれる
プログラムのコメントを書く時と同じような観点でnoteやwarnなどを入れておくとよい
- なぜそれが必要かわかりにくい時
- なるほどと思った部分や、役に立ったリンクなど
- 自分が失敗したポイント、誤解していたこと等
後書
- 良く言われているように、読みやすいコードを書くことと読みやすいドキュメントを書くことは似ていると思う。より良いコードを書くためのトレーニングと思えば、多少抵抗感が減るかも
- 誰かから質問された時にリンク渡すだけで済めば、自分の本質的な業務に割ける時間が増やせる。(なんなら、ドキュメントな見つけやすい形に配置できていれば勝手に見つけてくれるかも)
- 自分も色々模索中なので一旦整理してみた。意見やアドバイス待ってます！