ソフトウェア開発で使うべきでない日本語
- 「実装担当が仕様書通りのソフトを作ってくれない。どうしてだろうか?」
- 「自分が作成した仕様に対する確認の問い合わせが何度もある、こちらの時間も取られるしどうにかしたい。」
どうも、ベタオシです。
ソフト開発の仕事で、このような経験はありませんか?僕はありました。
当時はソフト開発って大変だなぁと他人ごとだったのですが、実は自分が作成している書類のせいでした。
これまで取り組んできた組み込みソフト開発の経験を元に、ドキュメントを作成する時に気をつけたい表現について紹介します。
何故、ドキュメントの表現に気を付けなければならないのか
表現に気をつけなかったドキュメントは読む人によって、ソフトウェアの動作が違ってしまうことがあるため、日本語の使い方には注意しなければいけません。
仮に、認識がズレたまま実装を進めていくと、どこかでバグが生まれてしまう可能性が高いです。数人で作っている規模のソフトなら軽微な問題になるかもしれませんが、数十人から数百人規模のソフト開発になると、大きな問題になります。
お互いに面識のない人同士がコミュニケーションを取り、このドキュメントはこのような動作を意図したものですよね?と認識を合わせなければなりません。
言葉で書くと簡単な印象を受けるかもしれませんが、実際にやってみると、多くの時間が必要になる、大変な作業です。
そして、ズレた認識を合わせたら、今度は実装箇所の修正と、その修正部分のテストを行う必要が出てくるでしょう。修正の影響が広範囲になってしまった場合、テストに使う時間もたくさん必要です。
この様に、ドキュメンの日本語が人によって違った意味に受け取れる状態にあるのはソフト開発の時間ロスを発生させるやっかいな問題なのです。
色んな読み方ができる日本語
ここからはソフト開発のドキュメントに使うべきでない日本語の一部を紹介します。どれも僕の経験がベースになっています。
「処理する」
一体何をすればいいのか分からない表現ですね。計算をするのか、文字を操作するのか、フラグを操作するのか、分かりません。
この言葉の前に固有名詞が接続して、「XXX処理」という表現もたまに見かけますが、こちらも具体的な操作が分からないので、つまりどうするの?とこちらが質問しなければいけない状態になります。
「確認する」
やりたいことは分かりますが、具体的な行動が見えてきません。値が同じことを調べるのか、大きい・小さいことを調べるのか、期待通りだったらどうするのか、期待と異なるときはどうするのか?選択肢が無数に浮かんできます。
「比較する」
これも比較の方法が具体的に示されていないので、同じことを調べるのか、大小を調べるのか、調べた結果どうすればいいのか?迷うばかりです。
文章を補足するための表や図やイラストを使おう
日本語に気をつけることは理解できたけど、どうすればいいのでしょうか?
僕は表や図やイラストを添えて、誰が読んでも自分の意図していることが同じものとして伝わるようにしています。
表や図、イラストはExcelやPowerPoint、ペイントツール等で簡単に作っています。文章の補足が目的なので、手の込んだものは必要ありません。
図やイラストを作成するために高価なソフトや広く使われていないソフトを使ってしまうと、半年以上経ってから修正や追記をする時に編集不可能になる可能性があるので、注意しなければいけません。
まとめ
キュメントを作成する時に気をつけたい表現について紹介しました。
ソフト開発をする様になって、日本語の難しさを再認識しました。頭で考えたことを伝えるのは大変な作業なので、できるだけ、図やイラスト等の補助を使っていきたいですね。
それではまた、ベタオシでした。

C/C++で組み込み系ソフトウェア開発の仕事を10年以上やっています。怪しげなデジタルガジェットが大好きです。