ボトムアップドキュメント作成のススメ：Enhancement Proposalの導入

428
NO IMAGE
目次

概要

  • トップダウンの重厚長大なドキュメントを書くのはしんどい。
  • ボトムアップな1つの機能の追加変更についてのドキュメントは書きやすい。
  • 弊社においてDesign Docsの形式は定着しなかったが、Enhancement Proposalは定着した。
  • ドキュメントも小さく始めよう。

Design Docsの導入の失敗

弊社では以前より製品開発の際に、内部資料として残すドキュメントに難があることが社内で共通認識となっており、これは特に製品への機能の追加変更について、その意思決定プロセスが記録として残されておらず、なぜそのような設計になったのかの情報が散逸しがちという形で悪影響があった。勿論Issue Trackerを用いた開発は行っているので新機能についての設計などの情報がまったくないわけではなかったが、Issue Trackerはあくまでもタスク管理であり、設計についてのドキュメントの場として適切ではなかった。

そのためDesign Docsを導入したらどうかという話は一時出たが、様々な理由で思っていたよりも上手く行かなかったという事実がある。

  • そもそもDesign Docsの書き方がわかっていなかった。
    • Design Docsについて解説したWebページなどは勿論あるのだが、それを自社のプロジェクトにどう導入するのが良いのかイマイチわからなかった。
    • Design Docsはソフトウェアプロジェクトの包括的な設計の事もあれば機能の追加変更に対する小さいドキュメントの事もあるようで、そういった点の認識が導入の際に擦り合わせられていなかった。
    • 結果、「包括的な設計」ばかりみんな着目して、むしろ今そこにあるタスクについての意思決定のドキュメントはおざなりなままだった。
  • ある程度プロジェクトが進んだ状態から包括的な設計のドキュメントを書こうとすると、どうしても様々なコンテキストを含んだドキュメントにならざるを得ず、恐らく本来のDesign Docsの想定よりも重厚長大なものを書かなければならないのでは、といった空気感になっていった。

こういった様々な理由でDesign Docsの導入はそれほど上手く行かなかった。（上記の問題をある程度理解している今ならもっと上手くやれそうではあるが。）

Enhancement Proposalの導入

かといってドキュメントを残すことに難を抱え、製品開発の意思決定においてなぜそうなったのかの情報が散逸するに任せるのはよろしくないので、何かしらもう少し導入しやすいものはないかと考えていた時に、参考にしたのがPythonにおけるPython Enhancement Proposal(PEP)であった。

勿論完全にPEPのフォーマットを真似たわけではないので異なる部分も多く、どちらかというとドキュメントを書き始めるための切っ掛けの一つとして名前を借りたに近くはあるのだが、それでも

  • 背景やモチベーションといったWhyの説明
  • どのように実現するのかについての提案

といった部分は共通項目として書くようにしている。基本的にそれらが記述されていれば文書のフォーマットやボリュームは一切問わない事にしており、とにかく無いよりあった方が絶対にマシという精神で割と緩めの運用になっている。

Enhancement Proposalを書く場としては、最終的にGithub Discussionsに落ち着いた。元々はGrowiで管理していたが、Growi自体の使い勝手の問題（主に検索やらEnhancement Proposalのリストアップなど）で別のツールに移行する必要が出てきてしまった。最初はIssue Trackerで行おうという案もあるにはあったが、

  • Issue Trackerではタスク管理が主眼となるが、そこでタスク管理ではないチケットが混在するのは分かりにくさがある。
  • 新機能や機能の修正についての議論なので、担当者もなにもない。チーム全体というアサインと考える事もできるだろうが……
  • Issueには明確なクローズがあるが、設計についての議論はしばしば半ば永続的なトピックとして長期に存在する。

といった理由から、Github Discussionsで行おうという事になった。

なお運用の際には、製品名の頭文字+EPの形の略称を付けたが、何気にこれも運用する上では重要な事だったように思える。例えば弊社のモデルグラフDB製品として開発を進めているtruncus graphであれば、Truncus Enhancement Proposal(TEP)という名称を付けて運用している。

導入した結果

Enhancement Proposalを導入した結果としては効果はあり、今まであまりドキュメントを書いてこなかったメンバーもある程度ドキュメントを書くようになった。

個々のドキュメントは物凄く小さく書き始められ、また必ずしも具体的な機能の設計ではないものでもよいので（現状の問題点への解決案をいくつか提示でもよい）、Discordなりslackなりで議論した内容について、設計・実装の責任者（あるいは言い出しっぺ）に「じゃあ今の内容をTEPに書いておいて」の一言でドキュメントを残せるのは実は重要ではないかと考えている。

これはなんとなくの感覚であるが、Design Docsのような一般的な名前を使うのではなく自分たちのプロジェクトに紐づいた固有名詞として定義し、その運用方法を自分たちに無理のない形で定めた事が功を奏したようにも思える。

依然として課題は残っており、ドキュメント作成そのものは相変わらず難しい事に変わりはないが、ボトムアップなアプローチと自社に合った運用方法を見つけることで、ドキュメントの質と量を向上させることができる事は実感できる結果となった。今後も上記の方向性でドキュメント作成について改善を続けていくつもりだ。