はじめに

いざ、ウォーターフォールバリバリ¹な開発スタイルだったところに、アジャイルな考えを適用しようとすると、ネックになるのが「ドキュメント」だと思います。

「金融系・お客様ほぼほぼ固定・サーバ保守する人がほとんど」な環境でアジャイル適用し始めた時に、断捨離を断行しました。
ただ、その時は捨て去りすぎて、少し問題²が起こっちゃいました。
本記事は、その経験を経ての整理結果です。

注意事項

• この記事は仮説です。この仮説での実証ができていません。当然、上手くいくことを保証するものではありません。（が、一度実務に適用した結果を受けたモノなので、参考にはなると思います）
• アジャイルってキーワード出してますが、ウォーターフォールバリバリなところにもきっと効果があると思うので読んでって。

断捨離アプローチ

いろいろ考えたのですが、「断捨離」を基準に説明するのがキャッチーで伝わりやすい気がしたので、「断捨離」というフレームワークで説明をしていきます。

断捨離は、「もったいない」という固定観念に凝り固まってしまった心を、ヨーガの行法である断行（だんぎょう）・捨行（しゃぎょう）・離行（りぎょう）を応用し、

• 断：入ってくるいらない物を断つ。
• 捨：家にずっとあるいらない物を捨てる。
• 離：物への執着から離れる。

として不要な物を断ち、捨てることで、物への執着から離れ、自身で作り出している重荷からの解放を図り、身軽で快適な生活と人生を手に入れることが目的である。ヨーガの行法が元になっている為、単なる片付けとは一線を引く。

wikipedia先生より

ドキュメントの断捨離方針

「断捨離」に照らすと、ドキュメントを見直す基本方針は以下になります。

1. 断 : 入ってくるいらない物を断つ
   • 【構築時】「設計書フォーマット」に脳死で従わない
     • 「フォーマットにあるから書かなきゃ」ってのは死ぞ
   • 【保守時】開発時のドキュメントをそのまま保守対象にしない
     • 保守に必要なドキュメント/要素だけに絞る
2. 捨 : 家にずっとあるいらない物を捨てる
   • 【保守時】参照されないドキュメントはゴミ箱に
     • 存在するからメンテナンスしなければいけない
   • 【両方】「ゲートキーパー」という役割の自然発生を抑制する
     • 「自分ごときが修正していいのかな・・・」「あの人に確認が必要だ・・・」とかを抑制しよう
3. 離 : 物への執着から離れる
   • 【両方】「設計」と「設計書作成」を分けてみる
     • 設計としてやるべきことは何か？
     • ドキュメントとして残すべきことは何か？
       • 例えばホワイトボードの写メではダメなのか？
       • 本当に必要なのは「ドキュメント」ではなく「ノウハウの共有」なのでは？
   • 【両方】今までのやり方から脱出できない組織文化に一石を投じてみる
     • 「政治的な問題」には政治を

結論

こっから「断捨離」関係無くなります。。。
順を追って、「断捨離」絡めつつ、この結論に持ってこうとしたのですが、筆者のスキル不足で諦めました³・・・
（一本道でここにたどり着いたわけじゃ無く、色々悩んで到達したので、文章で説明ができなかった。。。）

1. 開発に必要：存在しないとプログラミングのスピード/品質が著しく落ちるドキュメント
   • 外部設計書：顧客との瑕疵担保責任の話になるケースもあるので、「品質レベル：社外版」で作成が必要なケースが多い。
     • 一番丁寧に書くとしたら、IPAが出している「機能要件の合意形成ガイド（旧：発注者ビューガイドライン）」にならうのが良いかも。
       • 瑕疵担保とかの話でこじれるなら、ここまで書かないといけない気がする。
       • できればユーザー企業・ベンダー企業間で適切なパートナーシップを前提にして、ドキュメントの記載粒度を調整していきたいところ。
   • 内部設計書：本質的には、開発者が理解できれば良い。ここを細かくしすぎると、「製造」の裏返しになるため、ガチガチウォーターフォールだと無駄になりやすいドキュメント。
     • メンテしない：ソースコードを見ればわかる情報。ソースコードから生成できる情報。
       • ドラフト版レベルは作っても良い。
       • ドキュメントの形式で保守チームに引き継ぐ必要はない。
     • メンテする：「方式設計と機能要件をどういう考え方で適用したのか？」的な実装背景を支える情報。
       • コメントなどで指摘が容易に入れられるツール（Confluence/Qiita:Teamなど）で残していくのが望ましい。
2. 運用に必要：存在しないと障害対応や運用作業のスピード/品質が著しく落ちるドキュメント
   • コメントなどで指摘が容易に入れられるツール（Confluence/Qiita:Teamなど）で残していく
   • ExcelやWordなど、ファイルサーバー上でファイルに残した場合、メンテナンスのハードルが非常に高くなるので、陳腐化しやすい。
3. 契約に必要：存在しないと契約不履行・揉める原因になるドキュメント
   • 「品質レベル：社外版」レベルで作成が必要だが、極論、納品前で良い。

考えのポイント

上記結論にたどり着く道中で、ポイントになったことを以下に示します。

コストを評価する

• 「存在しないコスト」と「存在するコスト」を評価する
  • 存在しない場合に、『どの程度』のコストが発生するのか？
  • 存在した場合、メンテナンスのコストはどれくらい発生するのか？

※「コスト」は、短期的な「作成工数」「レビュー工数」はもちろん、長期的な「品質劣化に伴う障害対応工数」なども含まれる。
※「存在するコスト」「存在しないコスト」両方において、「開発者のストレス」も考慮した方が良い気がする。

「設計」と「設計書作成」を分ける

ドキュメントの修正に時間が取られ、本来やるべき「設計」の時間が削られるのは、望ましくない。
「設計」にフォーカスするなら、ドキュメントを書くより、ホワイトボードに書きながら対面で会話しながらやる方が質が高いモノになる。（はず）

みんなで「設計」、個人で「設計書作成」ってのが望ましいと思う。「設計書作成」は、納品前・運用開始前でも十分。
Let's 「モブ設計」。

メンテナンスのハードル

運用系ドキュメントは、「メンテナンスしやすい」がとても大事。
ファイルサーバーにおいておくと、「これ、修正して良いのかな・・・」的な問題が起きやすい気がする。
なので、ConfluenceやQiita:Teamなど、「誰でもコメントしやすい」状況を作れるツールを使うのが望ましい。

ドキュメント本体の修正には時間とかハードルとか色々あるけど、コメントなら「Aの部分は現在Bになってます」って簡単に書き込める。

ドキュメントツール
感覚的には、以下のような使い分けが望ましいと思います。

• Confluenceなどコメントしやすいツール：　「基本的な考え方」や「運用系のメンテが必要な情報」はこちら
• markdown： 「外部設計」など、差分管理が重要な情報。BDDをやるなら、BDDテストコードを代わりに利用できると嬉しい。
• ソースコード： 「コード」「テストコード」「コミットログ」「コードコメント」で書くものを分けるべし。

コードには How
テストコードには What
コミットログには Why
コードコメントには Why not

を書こうという話をした

— Takuto Wada (@t_wada) 2017年9月5日

適用に向けて

実際問題としては、この断捨離を現場に適用するのが一番難しい。
その中でも一番難しいのが、上司への説明。
そこさえ乗り切ればあとはトライアンドエラーでいけるはず。

ということで、「適用のために上司を説得するには」、私は以下が必要だと考えました。

• この変更が「QCD」にどのような影響をもたらすのか？
• 日頃の「信頼貯金」

QCDの説明

CDは、説明しやすいと思う。どれくらい現状に無駄があるのかを示せば良いだけだから。
Qは、「内部設計工程で検出した不具合」のウチ、本番障害として発生するのはどれくらいあるのか？を評価すれば良いと思う。

たぶんだけど、「ほとんど品質は悪化しない」ケースが多い気がする。なぜなら外部設計レベルのテストさえ網羅できていれば、本番障害にはならないから。
（その分、結合テスト工数がかかるけど、内部設計を丁寧に仕上げるよりは、低コストで済む気がする。）

※当然、データ準備等で、結合テストはすごく大変なんだ！という話なら別ですが、その場合ももう少し具体的に考えたいところ。例えば、データ準備が大変なら、「データに関するバリエーションだけ残ってればいいよね？」とか。
※品質評価を「step数あたりの不具合数」ではなく、「ケースの充足度」と「ケースの合格率」だけで評価するように変える必要がありそう。
※内部設計工程の品質保証について明言したいなら、内部設計工程を行なうのではなく、TDDを導入する方がよっぽど解決策だと思う。

信頼貯金

必ずしも自分の信頼貯金である必要はないと思っています。
影響を与えたい人に対して、信頼貯金のある人。その信頼貯金のある人に対して、信頼貯金のある人。って追ってけばいい気がする。

※ただし、曲がりなりにも「上司は話を聞く気がある」という文化が必要。

そもそもこれは社内政治の話だし、ここで話したい内容じゃないので、ここまでにして置きます。

さいごに

ちなみに、イケてるスタートアップや、R&D部門とかだと、ドキュメンテーション関連の問題ってどう解消してるんだろう？
プロダクト系の話は結構聞くけど、こういう泥臭い部分の話ってあんまり聞かない気がするので気になる。

こういう話あるよ！ってのがあれば教えていただけると嬉しいです。

以上です。

参考情報

設計書自体の書き方

そもそも設計書を書くということになったら読んでおきたい記事

• エンジニア歴20数年の私が、設計書を書く際に心がけていること：先人に学ぼう
• ドキュメント作成時のあるあるアンチパターン20：あるある

その他

• エクセルやワードの仕様書をマークダウン仕様書に変えよう：markdownで設計書を書く時に参考にしたい
• 忙しい研究者のためのテストコードとドキュメントの書き方：具体事例なのでイメージしやすい
• Best Practices for Agile Documentation：わりと綺麗にまとまっている。参考にするのよさそう。（英語）
• Confluence で技術者受けするアドオンのご紹介：紹介されているアドオンはウチでも使ってます。