2022/02/22 このエントリーをはてなブックマークに追加 はてなブックマーク - ドキュメントが必要な場合もあるが、それでもなるべくソフトウェアで解決したい

ドキュメントが必要な場合もあるが、それでもなるべくソフトウェアで解決したい

カテゴリ: ,




こちらツイートした内容について自分なりにあーだこーだ頭の中で考えてたものを文章に出来そうな気がしたので、ブログに書いてみる試みです。



プロダクト開発でドキュメントを書かないとどうなるか
https://product-develop.com/2c981f18e9924410bb266a5fd87343c2

特にこの記事の内容を批判したいとか反対だというわけではなく、居酒屋でオッサンがボヤいてるのと似たような感じの文章です。
…ただの個人の感想、というかポエムです




ドキュメントがどうしても必要な場合もある気はしている。が、やはり動作するソフトウェアの方がドキュメントより嬉しい。

自分の場合、どうしてもソフトウェアに出来ない部分はドキュメントでも良いけど、最小限にしたいなぁ。

これはトップダウンで決めたくない。どうしてもの時は、チームで決めてドキュメントを作って、チームでドキュメントを捨てて、をやっていきたい。


元記事のドキュメントが無いと開発効率が下がるという主張に関しては、色々開発のやり方次第なので断言できないよなぁ？とちょっと思った感じです。


前提、色々な会社があるので色々なチームもあり、色々な意見もあるよなというのがあります。
ドキュメントで開発効率が上がるという側面も分かる。チームや会社ごとに良し悪しがあると思います。

ざっくり以下のような感じ：

  • 開発するシステムやフェーズによってドキュメントの必要度合いは変わる
    • 例えばプロトタイプには要らないかも
    • 例えば何年も複雑な運用がされているシステムなら重要かも
  • 開発するチームメンバーによってドキュメントは必要度合いは変わる
    • 例えばメンバーの前提知識によって異なりそう
  • 開発するチームメンバーのコミュニケーションの形式によってドキュメントは必要度合いは変わる
    • 例えば非同期なチャットなどのコミュニケーションが多ければドキュメントの重要度が上がりそう
    • 例えば同期的な口頭でのコミュニケーションが多ければドキュメントの重要度が下がる
  • 開発するチームメンバーのコミュニケーション量によってドキュメントは必要度合いは変わる
    • 例えば会話が頻繁にされないのであればドキュメントから情報を拾う必要がありそう
  • 開発の進め方によってドキュメントの必要度合いは変わる
    • 後述

僕はアジャイルもアジャイルマニフェストもナンモワカランですが、
「ドキュメントは動作するソフトウェアでどうにも出来なくなった時の最後の手段」という気がしています。


まず、色んなものごとを動作するソフトウェアに落とし込めないか最大限検討した上で、
どうしてもドキュメントを残した方が良いという決断になった場合に書くかも、というのが個人的な感覚です。

むかーし、ドキュメントを綺麗に一式揃えておくことを丁寧にやっていた時期もあったのですが、丁寧に書いた文章のうちちゃんと読まれるのは1割ぐらいだったような気がするんですよね。体験談。

それなら、ドキュメントはある程度の叩き台に留めて、作った会話した方が早いみたいなことが多いなと。



コードからドキュメントが生成され、コードをいじればドキュメントが修正されるみたいな世界が僕は結構好き。

まぁ、具体例だとirofさんのやつですね。
https://speakerdeck.com/irof/kodowodomannakaniju-etashe-ji-apuroti

ドキュメントは必要だがドキュメントのメンテはしたくない。コードのメンテならまだ良い。
心理的にはドキュメント編集ツールは開きたくないが、IDEやエディタは開きたい。僕は。

元記事で言えば、

＞SSOT(Single Source Of Truth)を意識してドキュメントを更新し続ける

個人的にドキュメントを更新し続けるの嫌だなぁ、ってなっちゃうのですよね。
ドキュメントを腐らすなという気持ちはとても分かりますが。


たとえば、swaggerとかも直接swagger.jsonをいじってメンテするという道もあると思うのですが、
自分はコードからswagger.jsonを生成したい。コードを直したらIDLが生成される世界。
というか、そういったやりかたの開発をさせてもらった事があるんですがめっちゃ便利でした。


例えば環境構築が手作業であれば、ドキュメントは必要だと思うのですが、
Infrastructure as Code的なものがうまく実現できればドキュメントは不要かもしれないです。
でもInfrastructure as Codeも結局Codeだったりymlだったりするのでそのものから読み取れない細かな部分があり(ymlツラく無いですか？？)。
その部分に関しては最小限のドキュメントとして用意したりするのも良いかもしれません。
Infrastructure as Codeなものが何かviewerでわかりやすく見えれば良いのかもしれません。
Infrastructure as Codeとは文脈ちょっと違いますが、GitHub Actionsなんかは、ymlからパイプラインがグラフィカルに見えて(一応)分かりやすいです。


cucumberとかgaugeとか。
テストシナリオが明確であればユースケースに関するドキュメントは要らないかもしれません。

あとユニットテストとか。明確にテストケースで分かれば実装のドキュメントは要らないかもしれません（または、減るかもしれません）。


構成図とか、フローとか、アーキテクチャ図的なものとかお絵描きしたくなることはあります。

でも最近は整ったドキュメントとして残すというより、その場限りの議論のためのお絵描きとした方が良いかなという気がしています。
思い出すために見直すとしても整ったドキュメントという前提は置かないかも。

図とか箇条書きとかもドキュメントでしょ！と言われると広義ではそうですよねという感じがします。

でもDesign Docというほど洗練されたものは要らない気がします。


これも面白かった↓


Design Docs のいけすかなさ
https://messagepassing.github.io/011-designdocs/01-morrita/



元記事で書かれていたPRD(Product Requirements Document)や
Design Docなどのレベルまでは書かないにしてもメモ書きなどは必要な時もあるかもしれません。

あるとすれば、難易度が高い部分やとても重要(クリティカル)な仕様などは
そういったドキュメントをあえてきっちり書くということも必要かもしれません。
お堅いシステムだと結構ドキュメントしっかりな感じになりますよね、きっと。
お堅いシステムでもドキュメントで担保するかそれ以外(例えばテスト)で担保するかである程度変わってくるかもしれませんが。


例えば、運用がめちゃくちゃ複雑だったり慎重になる必要があれば欲しくなる手順書。
唯一、自分は手順書は好んで書きたがる方かもしれないです。認識ズレるのが怖いので。

みなさんも手順書を作ったりすると思うのですが、なるべくならその手順をたくさん踏む複雑さを持ち込みたくないというか。

複雑になってしまったが故にドキュメントが必要なのであれば、複雑さを無くすのが理想なんだなと思ったりします。


あ、あれは僕の中では紙芝居、もしくはフリップ芸の補助なのでドキュメントではありません…！


根底の気持ちはここかもしれません。ドキュメントを綺麗にしても届く人って少なかったりするというか。過剰になってしまう気もするんですよね。
コードだとそうはならない(ホンマか？)のだけど、ドキュメントだと過剰なぐらいに厳しかったりってことないですかね？
単純にそういう印象が自分の中であるだけかもしれません。

あと単純にコード書いたり何かを動かしてる方が楽しいよねっていうところがあります。

こんな長文でブログ書いてて矛盾してるような気もしないでも無いですが、文章書くことも嫌いでは無いです。

こうなってくると、ドキュメントの定義とはそもそも何？って気もしてきた。

開発にまつわるドキュメントは最後の手段、最小限が良いのではないかみたいな感じのお話でした


  • いやいや違うがな
  • 分かる
  • 分からん
  • 長文乙

など何かあればご意見ご感想お待ちしてます！




Posted by at
このエントリーをはてなブックマークに追加
カテゴリ: ,

0 件のコメント:

コメントを投稿

GA