地方エンジニアが感じる地方・中小企業での悩み

そのドキュメント、今でないとダメですか?

»

 開発業務に携わる方たちだけではなく、多くの方々は、仕事でも仕事以外でも「ドキュメント」を書いていることと思います。業種によっては、ドキュメントを書くことが本業で、それ以外の業務の割合が少ない、という方もいるのではないでしょうか。

 私が属する開発業務の世界でも、やはり多くのドキュメントを書くことがあります。それは設計書であったり、ユーザーや受注元とのやりとりであったり、いろいろな種類のドキュメントを書きます。

 こと開発の世界に限ると、ドキュメントを書き記す理由は大きく分けて2つあります。

 1つは、「今システムを作るために必要であるため」であり、もう1つは「後で何か不慮の事態が起きた際に利用するため」です。開発標準として多くのドキュメントが定義されていますが、このコラムを読んでいる皆さんは、標準をアレンジしていることが多いのではないでしょうか。

 基本としてドキュメントは必要なもの、というのは疑う余地のないところだと思います。ですが、ドキュメントを書いているときには、「これは本当に必要なものなのだろうか」と不思議に思うこともあるのではないでしょうか。

 作成される大量のドキュメント、しかしその大半はその後日の目を見ることもなく、ファイルキャビネットやファイルサーバの中で眠り続けることも多々あります。もちろん「万が一の事態のため」という目的もあるので、一概に日の目を見ないことが悪いと言い切るものではありません。しかし中には「実は不要なもの」「今の時勢に合わないんもの」であり「体裁を整えるため」に、とりあえず作るだけ作ってしまうものも紛れ込んでいるのではないでしょうか。

 そういった類のドキュメントが増えるに従い、現場にかかる負担は増加していき、本来やるべきことができなくなるという悪循環を生みだします。そのような状況に陥るのは、大抵せっぱつまってきたころになりやすく、弱り目に祟り目というか、なんとも言い難い状態になることもそう少なくはありません。

 個人的に考えるのは、ドキュメントというものは「必要な種類」のものを「必要な量」作成できることがベストであり、種類が少なくても量が多くてもあまりいいことではないということです。

 ただ、難しいのは、「適した種類」と「適した量」を作るということです。携わる案件の規模にもよるでしょうし、関わる人々の求めるレベルにも左右されるでしょう。ある案件の際は小規模であってもしっかりしたレベルのドキュメントを大量に求められたり、別の案件では要件定義や詳細設計など、必要最低限なものだけでよいというように、さまざまなケースがあります。

 この辺りを考えると、標準的なドキュメントでも、場合によってはそれほど重要視しなくてもいいのではないか、と考えることがあります。もちろん必要がないのではなく、体裁を整えるために時間を費やしたりする必要がない、という意味合いでですが、「見てくれ」よりも「中身重視」で進めることがあってもよいのではないでしょうか。

 極端にいえば、開発途中であれば体裁は二の次で、中身の記述がはっきりとしていればよく、レイアウトが微妙にずれているとか、多少冗長な記述があるとか、本質的な部分から外れる点においては「後で」修正する方法をとることも、1つの進め方です。

 もっと進めれば、議事録は音声や動画だけで最初は済ませてしまうとか、要件定義も詳細設計も最初の時点では箇条書きレベルでも許してしまうとか、「あるのが望ましい」ものならばいっそのこと「悪いけどない」としてしまうのも、一概に間違った方法とはいえません。実際のものづくりに集中できれば、それはそれで良い方法なのだと考えます。

 このような考え方を進めると、開発に付随するさまざまなイベントにおいても力を入れるべきところに力を集中し、抜いてもよいところは抜く、というメリハリのきいた仕事ができるようになるかもしれません。例えばドキュメントのレビューは大事なイベントですが、そこで行うのは体裁よりも内容にのみ限定するとか、コードレビューも同じように内容に限った点を集中的にレビューすることで、その時点でかける必要のない力を、別のところに割り振ることもできるようになるでしょう。

 各フェイズごとにしっかりと体裁も整えられたドキュメントを作成できるのは非常に素晴らしいことです。ただそこに時間を費やすあまり、本来の目的がおろそかになってしまうようであれば、一度そのバランスを見直すことも大切なのではないでしょうか。ドキュメントが揃っていたとしても、一番大事なシステムやアプリケーションがなければ、ただの資料の集まりでしかないのですから。

 これを書いている私自身、このように仕事が進められればいいな、と思うほど、理想が混じっています。現実の現場では「そうは言っても体裁よく作らないといろいろなところにマズイでしょ!」という状況であることばかりです。ですが、理想だからといって、諦めずに常に良い方向へ改善できるよう、少しずつでも考えていきたいです。

Comment(3)

コメント

Jitta

なかなか興味深いですね。
 私が思うのは、次のドキュメントは、その時に作成しておきたい、ということです。
・他者(他社、他部門)との取り決め
・他者とのインターフェイス部分
・エンド ユーザーの要望
・開発の範囲

つまり、「何を作るのか」という目標をはっきりさせるためのドキュメントです。
これらは、他者と話をしながら決まることになると思いますが、例えばマインド マップのような形で、その場で作りたい。「動画や音声で」と書かれていますが、音声を聞くのと、書かれた物を読むのとでは、読むスピードの方が圧倒的に速い。また、検索性も、書かれている方が高い。そして、その場で認識あわせができる。うん、おそらく、一番大事なのは、あなたの理解と私の理解は一致していますよね?という確認だと思います。


> コードレビューも同じように内容に限った点を集中的にレビューする
 この辺は、ツールに任せてしまうのも手です。「内容以外はツールに任せる」ということです。C# なら、StyleCop とか。働き始めた時に所属した部署では、SunOS4 で C 言語を使っていましたが、「indent コマンドに**オプションを指定して整形する」というルールでした。Solaris になって、indent コマンドがなくなったのが悲しい。

airwing

民需だとわかりませんが、官公庁相手に仕事をしていると「仕様書に載っているから作らなければならない」無意味なドキュメントが多いのがなんとも……。
しかもそういう案件に限って体裁の「、」と「,」が違うなどというレビューで長時間取られたり……。
難儀なものです。

Ahf

Jittaさん、airwingさんコメントありがとうございます。

>また、検索性も、書かれている方が高い。そして、その場で認識あわせができる。
>うん、おそらく、一番大事なのは、あなたの理解と私の理解は一致していますよね?
>という確認だと思います。

その通りだと思います。言われているように「何を作るのか」をはっきりとさせるために、ドキュメントが役に立つ、と私も思います。なかなか、その目的を達成できているドキュメントというのが少ないのが、いかにしっかりとしたドキュメントを作成することが難しいのを表しているのかな、などとも。

自分のドキュメント作成レベルも大したものではないので日々努力ですが、できるだけシンプルにお互いの認識が一致するようなものを書き上げようと、毎回考えながら書いてます・・・。

そういえば最近はStyleCopをはじめ、その類のツールを調べてないなぁ・・・。

>民需だとわかりませんが、官公庁相手に仕事をしていると「仕様書に載っているから
>作らなければならない」無意味なドキュメントが多いのがなんとも……。

私は官公庁相手にお仕事させてもらったのが、大分昔になるので今の事情には明るくないのですが、無意味と思われるドキュメントは多いのですね。言葉の端々からも、その難儀さが伝わってきました。このようなところを、どうにかできればいいのでしょうが・・・難しいですよね。

コメントを投稿する