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

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

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

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

5．文書作成バグの兆候と対策

5.1 兆候

　文書作成のバグには、発生する兆候はなく、作成者の力量が試されます。

5.2 対策

　文書作成バグの対策法を以下に示します。

5.2.1 文書校正ツールを使用する

　皆さんが普段使用するマイクロソフトの「Word」には、文書校正機能が付いています。機能を有効にしておくと、完全ではありませんが、明らかな間違いを指摘してくれます。例えば、過去に筆者が間違えた「Deadrock」もエラーであると指摘します。

5.2.2 間違えやすい文字を一括検索する

　間違えやすい文字は、文面を追っているだけでは分かりません。そこで、「メモリの解放とメモリの開放」「シミュレーションとシュミレーション」のような間違えやすい単語をまとめておき、文書を見直す際に検索をかけましょう。

5.2.3 紙に印刷する

　不思議なことに、PCの画面で見るより、紙に印刷したほうが間違いを見つけやすくなります。若者は目がよいので必要性を感じないでしょうが、間違いの多いエンジニアは印刷して、図番号などを再チェックすることが望ましいでしょう。

5.2.4 数日寝かせる

　作成したプログラムを3日後にもう一度確認してみると、「何でこんな書き方をしたのだろう」と思うことがありますね。文書作成でも同じで、文書の間違いが多く見つかります。時間に余裕がある場合は、数日後に再確認することをお勧めします。

5.2.5 レビューを依頼する

　周りの人にレビューを依頼するといいでしょう。いくら自分で自信を持った文書を記述しても、他の人から見るとおかしい箇所が多く見つかります。ただし、付箋紙や口頭での修正指示などをすると意思疎通の関係上、終わらなくなることがありますので、指摘者自らが修正することを強くお勧めします。

5.2.6 実行可能な仕様書を作成する

　図の記述方法によっては、ツールで実行結果を確認できるものがあります。状態遷移図ならば、Simulink／Stateflowなどのツールを使うと、シミュレーションで確認できます。ツールがない場合は、状態遷移表を参考に机上デバッグしてみてください。ペンで追っていくうちに間違いが見つかります。

6．まとめ

　下記に文書作成のバグをまとめます。

• 文書作成のバグは、文書の形式上のエラーのことであり、このバグが開発対象に大きな影響を与えることはほとんどないが、顧客に不信感を与える可能性がある
• 文書作成のバグは、主に、誤字脱字、図や表番号を付け忘れる、図・表の作成ミスがある
• 文書作成のバグの兆候はなく、作成者の力量による
• 文書作成のバグを防ぐためには、「文書校正ツールを使用する」「間違えやすい文字を一括検索する」「紙に印刷する」「数日置いた状態で再確認する」「レビューを依頼する」「実行可能な仕様書を作成する」などの対策をするとよい

7．終わりに

　ソフトウェア開発業務の中で大きな比率を占める作業の一つが、文書作成でしょう。今回は、筆者の経験を踏まえた文書作成のバグを取り上げました。このバグは、プログラムの動作に大きな影響を与えることはありませんが、顧客の信頼を確保するために、キチンとした文書を提出できるようにしましょう（誤字脱字衍字などのエラーが多いと、仕様や設計のバグも多いと考えます）。ただし、形式的なバグばかりを気にしすぎて、本質のバグを見落とすことがないように気を付けてください。

　本シリーズのバグ百科事典は、バグに関する基礎知識を増やすためのものですが、実践力を磨きたいという方は、過去シリーズか書籍の「バグ検出ドリル」に挑戦していただければと思います。

山浦先生執筆の書籍「ソフトウェア技術者のためのバグ検出ドリル」が発売！

　2019年11月27日に、山浦恒央先生が執筆した書籍「ソフトウェア技術者のためのバグ検出ドリル」が日科技連出版から発売されました。本連載「山浦恒央の“くみこみ”な話」とTechFactoryの連載「組み込みエンジニアの現場力養成演習ドリル」をベースに、大幅加筆、改訂した内容になっています。

　内容は、「デバッグの詰将棋」で、要求仕様定義、設計、コーディング、テスト、保守の5フェーズでの「バグを埋め込んだ仕様記述やソースコード」を読んで、バグをピンポイントで見つける問題集になっています。全部で31問あり、難易度は初級から上級まで、いろいろです。興味のある方は、Amazon.comや書店でチェックしてください！

【 筆者紹介 】

山浦 恒央（やまうら つねお）

東海大学 大学院 組込み技術研究科 非常勤講師（工学博士）

1977年、日立ソフトウェアエンジニアリングに入社、2006年より、東海大学情報理工学部ソフトウェア開発工学科助教授、2007年より、同大学大学院組込み技術研究科准教授、2016年より非常勤講師。

主な著書・訳書は、「Advances in Computers」 （Academic Press社、共著）、「ピープルウエア 第2版」「ソフトウェアテスト技法」「実践的プログラムテスト入門」「デスマーチ 第2版」「ソフトウエア開発プロフェッショナル」（以上、日経BP社、共訳）、「ソフトウエア開発 55の真実と10のウソ」「初めて学ぶソフトウエアメトリクス」（以上、日経BP社、翻訳）。