注意: この記事は1年以上前に掲載されたものです。情報が古い場合がありますのでお気を付け下さい。
最近、コード書くよりも仕様書や定義書といった、実装面よりもどういう挙動をするのか、何を使うのか、何をするのかといった、ドキュメント類を書く機会が増えているが、それが思ったよりも大変である。ここでは個人的な意見を述べて見たい。
まず、ドキュメント類は多くの場合、一定のフォーマットが指定されており、それは多くの場合はExcel、他にはWord形式も考えられる。また、その使い方も書類によって変わってくるが、基本的にはバージョン管理の概念がコーディングとは違い、Excelであればシートを分ける、Wordであればファイルを分ける場合が多い ((ソースコードやMarkdown/HTML含めたプレーンテキストのドキュメントならバージョン管理の方が望ましい)) ため、戸惑いを覚えるときがある。また、コーディングを行なっているとあまりに非効率な管理方法を行うケースや書き方を強いられることもあるので、その点が癪ではある。
また、何を書けばいいのかという点でも悩むことがあるが、こちらのついては以下踏まえていれば問題なくなった。
- 何を求めているのか簡潔に書く
- 状況にもよるが、専門知識を持っていない人でも理解できるように書く
- 何が必要なのかを確認しておく
- 長い文章は避ける。必要な場合は、あらかじめ分けておく
- まずは合格ラインを目指す
- 何度もやって改善していく
これらをしっかり押さえておくことで、ちゃんとしたドキュメントを書けるようになるだろう。
必要十分なドキュメントを作るのは可能だが、完璧なドキュメントを作るのは不可能である。それを念頭に入れた上で、ドキュメントは作りたいものである。
ウェブマスター。本ブログでITを中心にいろいろな情報や意見などを提供しています。主にスマートフォン向けアプリやウェブアプリの開発を携わっています。ご用の方はコメントかコンタクトフォームにて。
