設計書やPRD(Product Requirements Document)などのドキュメントについて、鮮度を落とさずに保守していくか、というのは、常に頭を悩ませる課題である。
「ソースコードがきれいに書かれていれば、それを読めばよいはず」という説は一理あると思うが、個人的にはやはりドキュメントは必要と思う派だ。 もちろん、きれいなソースコードを書くことを目指すのは当たり前として。
ソースコードは「現状の動作がそうなっていること」は表明できるものの、「本当にその動作が意図したものか」を表明するものではないからだ。また、そういった背景/Whyの部分はコメントに書かれているべきだという説もあるが、コメントだけでは読み取れない、より深いコンテキストが欲しくなることもある。
なので、ドキュメントもしっかり書くことを今のチームでは目指している。
今は、某SaaSに備え付けのWikiをストック情報のハブにしていて、基本的にはここに必要な情報を集約させるように心がけている。
大きいファイルなんかは、別のストレージに置いているが、必ずWikiからたどれるようにしている。
（余談だが、出来にすごく満足しているわけではなくて、最低限の機能だけをもったWikiという評価だ。なので、Notionとか使ってみたいなと、軽く持ち掛けたことはある。）
話を戻して、ドキュメントの運用で意識しているのは以下の点だ。
- 同じ情報を複数の場所に書かない。
- 置き場所を事前にかっちり決めすぎない。
これにより、
- （情報を得る側の視点で）雑にでもとにかく検索すれば、必要な情報がhitすること
- （情報を貯める側の視点で）どこに書くべきかに頭を悩まないこと
を図り、情報の活用サイクルが回るように心がけている。
個人的にはそこそこうまく回っているように感じてはいる。
「置き場所を決めない」という発想は、アマゾンの倉庫だったり、野口 悠紀雄氏の「超」整理法（学生の頃なので十数年以上前の記憶だけど）と通じるところもあり、モノや情報を整理する上でのコツかもしれない。
とはいえ、まだまだ課題もある。
最近の開発はモノリシックなアプリケーションではなく、Lambdaの利用などが進んできたこともあり、各機能（サービス）ごとの小～中規模なまとまりでドキュメントを作ることが多くなってきた。
その一方で、完全にそれらがきれいに分離できているわけでもないので、共通で参照するデータストアに関するドキュメントなど、機能横断的なドキュメントの探し方がけっこうしんどくて、テーブル(DynamoDB)やS3バケットの逆引きなども作りながら、まだまだ試行錯誤の段階である。こういったことをやりだすと、どんどんドキュメントだけが太っていきそうな懸念がある。
昔から変わらないテーマなんだろうけど、未だ銀の弾丸はないんだろうなと、そんなことを、Slack初の値上げのニュースを見て思ったのであった。
ちなみにSlackはフロー型の情報ストックだと思うのだが、とにかく検索の応用の幅が広くて、過去のQ&Aとかも簡単に探せるので、今となっては巨大なナレッジベースの一翼になりつつある。もちろんそのためには有料プランを契約する必要があるけど。
というわけで特にオチはないけれど、この辺で。
同じような主張の記事も過去にあるだろうが（多数派かもしれないし少数派かもしれない）、何となくポエムとして書いてみた。
