「それを見れば、わざわざアプリを実際に動かして確かめなくてもアプリの挙動や仕組みがわかる」
という仕様書を目指す場合、どう書けばいいんだ?
この場合、お客さんに見せるのを想定はしていない。どちらかといえば内部での情報参照のために用いるものだ。
いや、単純に愚直に、アプリの情報を書いていくしかないのはわかってる。
問題は、
- 「情報量と、情報の探しやすさ/見やすさを両立した書き方がわからん」
- 「情報量と、メンテナンスのしやすさを両立した書き方がわからん」
- 「改修の頻度・速度に比例して仕様書をメンテナンスするハードルが高くなる」
という点。
もちろん、メンテナンスしなければいけないのはわかっている。
問題はそれに対する心理的負担が大きいという点だ。
「仕事なんだからしょうがない」と考えるのは簡単だが、アプリを改修するのも仕様書を作るのも人間だ。
「めんどくさい」と思うポイントが増えれば増えるほど、モチベーションも下がる。
モチベーションが下がれば、仕事の質も下がる。
そうならないために、仕様書のメンテナンスがなるべく苦痛じゃないように工夫するのが大事だと思う。
だが、そうするための工夫ってどうすればいいのだろう。
コードの内容を逐一書き留めるような仕様書は意味がないと思っている。
具体的なソースコードなんて常に修正が入るし、そのたびに仕様書を修正するのはそれこそ苦痛だ。
問題は機能を網羅できているかである。
なぜ仕様書が必要かを考えると、
- 実装漏れを防ぐための基準となるドキュメントが必要
- 新しく人員が入った時、プロジェクトの理解の手助けとして大いに役立つ
などいくつか理由がある。
だけど、その仕様書が現状に即していなければまったく意味のないものになってしまう。
「この仕様ってどれ見ればいいですか?」
「ああ、それはこの仕様書に書いてあるよ」
「ありがとうございます」カチカチ
「えっ…更新日が1年前だし、どこに書いてあるのか全然わからん…ていうか、貼ってあるスクリーンショットが今のアプリとぜんぜん違うんですけど!」
結局実際のアプリの動きと、ソースコードをにらめっこすることで理解を深めていく。
それはそれで大切な経験だけど、やっぱり「仕様書が更新されていない」というのは非常に残念な気持ちになる。
たとえその古い仕様書に必要な情報が書いてあっても、「メンテされていない」「情報が探しづらい」という事実が脳の思考を邪魔してくる。
それに「このプロジェクト大丈夫かな…」と考えるきっかけになりやすい。
誰だって、今やっていることに不信感を抱いて仕事したくないんですよ。
だから、ドキュメント整理はすばやく簡単にできるような工夫をすべきだし、
過去を遡るのに有用なものを作っておくのが大事だと思う。
更新されないというのにも理由は複数あると思う。
- 更新するのが面倒くさいので誰もやりたがらない
- 更新する時間をタスクとして設けていない
- 誰も仕様書を重要視していない
誰も重要視していないし使われないなら無くてもいいよねって話かもしれないけど、
本来あったほうが便利になると思うんですよね。
まずは自分がそのメンテ役を買って出るのが良いと思う。
そうしてメンテされた仕様書が、役立った!と思われるような機会を作っていく。
そうすれば周りの反応も自ずと変わってくる。
ただし自分はエンジニアなのに「仕様書メンテする人」として扱われていくので、
そこからは作業分担やルール整備を提言していくことになると思う。
ちょっと思考が脱線しちゃったけど、誰か教えてほしい。
メンテしやすい仕様書って何だ?そのための工夫って何だ?
いや、仕様書じゃなくても良い。
- 実装漏れを防ぐ
- 新しく人員が入った時、プロジェクトの理解の手助けを作る
この目的を果たすためのノウハウって何だ?