ソフトウェア技術者のためのバグ百科事典（6）不信感を生む“文書作成のバグ”：山浦恒央の“くみこみ”な話（127）（1/3 ページ）

ソフトウェア技術者に向けて、バグに関する基礎知識をまとめていく新シリーズ「バグ百科事典」。第6回は、ソフトウェア開発業務の中で圧倒的に大きな比率を占める「文書作成」における間違い、「文書作成のバグ」を取り上げます。プログラムの動作には影響しませんが、その文書を読んだユーザーに不信感を与えかねない危険なバグなのです。

[山浦恒央 東海大学 大学院 組込み技術研究科 非常勤講師（工学博士），MONOist]

※本記事はアフィリエイトプログラムによる収益を得ています

⇒連載「山浦恒央の“くみこみ”な話」バックナンバー

1．はじめに

　バグ百科事典は、筆者が気になったバグを紹介し、読者の皆さまに「バグの早期発見」と「バグの未然防止」に役立てていただくものです。本コラムによって、より良いソフトウェア開発のお役に立てればと思います。

2．文書作成のバグ

　ソフトウェア開発業務の中で、圧倒的に大きな比率を占める作業が、文書作成でしょう。エンジニアが一つの製品を作るには、要求仕様書、設計書、テスト仕様書、報告書などあらゆる文書を記述する必要があります。

　文書を作成するのは人間ですから、間違いも存在しますね。文書のエラーにはさまざまなケースが考えられます。今回は、文書の形式上の間違いを「文書作成のバグ」と定義します。例えば、「誤字脱字」「図・表番号の間違い」「図・表の記述ミス」などです。よって、「文章が分かりにくい」「仕様書の表記が正しくない」は今回の範囲外とします。

　誤字脱字や図番号のエラーは、プログラムの動作にはほとんど影響しませんが、読んだユーザーに「真面目に設計しているのだろうか」との不信感を与えます^※1）。管理者は、各種文書を提出する前にしっかりと確認する必要があります。

※1）筆者の経験上、「仕様書、設計書、ソースコードで記述した内容は正しく、バグはないが、誤字脱字多く、図表の番号が正しくない箇所が多い」というケースは、まず、ありえません。表記がキチンとしていない場合、中身にも大量にバグがあります。誤表記が多いと、仕様や設計のバグもたくさんあると考えられます。表記上のエラーを軽視してはなりません。

3．文書作成のバグの分類

　バグの分類方法や、発生頻度により、以下のバグに着目します^※2）。

1. 誤字脱字衍字（えんじ）
2. 図・表番号の間違い
3. 図・表の記述ミス

※2）その他の文書作成のバグとして、「社内フォーマットの逸脱」が考えられます。社内には標準的な文書フォーマットがあり、それを基に文書を作成することが一般的です。それにより、作成者ごとのフォントや文字サイズを統一でき、読みやすくなります。一方、いくら文書の内容がよくても、フォーマットに従ってないだけで問答無用でNGとなる硬直的な面もあります。

3.1 誤字脱字衍字

　誤字脱字衍字とは、「間違った文字」「文字の抜け」「余計な文字」を言います。エンジニアに限らず誰もが経験します。

3.2 図・表番号の間違い

　文章が中心の文学作品と異なり、ソフトウェア開発では図や表を駆使します。図や表はきちんと描いてあるのに、「対応する番号がない」「番号が間違っている」などがありますね。作成者の視点に立つと、新しい図を挿入・削除を繰り返しているうちに分からなくなり、発生すると考えられます。

3.3 図・表の記述ミス

　ソフトウェア開発では、作りたい製品をエンジニアに分かりやすく記述するために、状態遷移表やDFD（データフローダイヤグラム）などを使用します。これらの記述はプログラムを作るうえで大変便利なのですが、記述ミスがあるとかなり厄介です。