ドキュメント書くの大変だが

注意: この記事は1年以上前に掲載されたものです。情報が古い場合がありますのでお気を付け下さい。

最近、コード書くよりも仕様書や定義書といった、実装面よりもどういう挙動をするのか、何を使うのか、何をするのかといった、ドキュメント類を書く機会が増えているが、それが思ったよりも大変である。ここでは個人的な意見を述べて見たい。

まず、ドキュメント類は多くの場合、一定のフォーマットが指定されており、それは多くの場合はExcel、他にはWord形式も考えられる。また、その使い方も書類によって変わってくるが、基本的にはバージョン管理の概念がコーディングとは違い、Excelであればシートを分ける、Wordであればファイルを分ける場合が多い ((ソースコードやMarkdown/HTML含めたプレーンテキストのドキュメントならバージョン管理の方が望ましい)) ため、戸惑いを覚えるときがある。また、コーディングを行なっているとあまりに非効率な管理方法を行うケースや書き方を強いられることもあるので、その点が癪ではある。

また、何を書けばいいのかという点でも悩むことがあるが、こちらのついては以下踏まえていれば問題なくなった。

  • 何を求めているのか簡潔に書く
  • 状況にもよるが、専門知識を持っていない人でも理解できるように書く
  • 何が必要なのかを確認しておく
  • 長い文章は避ける。必要な場合は、あらかじめ分けておく
  • まずは合格ラインを目指す
  • 何度もやって改善していく

これらをしっかり押さえておくことで、ちゃんとしたドキュメントを書けるようになるだろう。

必要十分なドキュメントを作るのは可能だが、完璧なドキュメントを作るのは不可能である。それを念頭に入れた上で、ドキュメントは作りたいものである。

タイトルとURLをコピーしました