理系のための文書作成術(6) ―― 仕事で文書を「書かされている」あなたへのメッセージ

塩谷 敦子

●ドキュメンテーションは仕事を進める能力を育てる

 開発文書に対する理解が深まり,その重要性を認識するようになると,適切な文書を書く力を身に着けたいと思われることでしょう.ここで,適切なドキュメンテーションを心がけることが,書く能力だけではなく,自らの仕事を正しく理解し,それをやり抜く開発者としての技術力を高めることをお話しします.

 (1)「正確であること」,(2)「読みやすいこと」は,技術文書全般に求められる事柄です.開発文書を例に考えてみましょう.要求定義や設計,実装などの技術的に難解な内容を,読み手が容易に理解できるように書かなければなりません.そのためには,書き手自身が,その情報を整理し,完全に理解していなければなりません.その上で,正確にかつ読みやすく書く能力が求められます.

 さらに,(3)「目的に合っていること」は,文書が求められる役割を果たしていることを意味します.開発文書には,該当する工程で,その作業担当者が行うべきことが定義されていなければなりません.担当者は,作業工程で行うべきことを理解し,自らが有するソフトウェア技術力を使って開発にあたり,実際に行ったことを記述しなければなりません.さらに,次工程で行うべきことも理解し.次工程に伝えるべきことを漏れなく記述する能力も求められます.

●仕事を進める二つのヒント

 ドキュメンテーションに仕事を反映させるヒントを二つご紹介しましょう.

◆言行一致の文書を書く

 ドキュメントの見出しと冒頭の要旨(文書の内容を簡潔にまとめたもの)は,これから書こうとする内容を端的に伝えるために,最初に書きます(第3回を参照).また,本文を書くときは,見出しと本文を一致させて作業のブレをなくします.

 「見出し」と「本文」を一致させることは,「行うべきこと」を最初に決めて,その通りに「実際に行うこと」につながります.また,文書の冒頭のみならず,章や節においても,「冒頭の要旨」を先に書いておくことが,後に続く記述の内容,すなわち行った作業内容を規定することにつながります.これらは,「言行一致」といえます.「行うべきこと」(言)を決め,行ったこと(行)を一致させることが大切です.見出しと本文の一致や,冒頭の要旨から詳細な記述への流れは,まさに言行一致を文書によって体現するものです(図1).

図1 見出しと本文で言行一致

 

◆記述の「入力」と「出力」を区別する

 一般的な技術文書の書き方のこつとして「事実と意見を書き分ける」(1)(2)(3)(4)ことがよく挙げられますが,仕事を表現するドキュメンテーションでは,記述の「入力」と「出力」をしっかりと区別することも同様に重要であると筆者は考えます.ある仕事を記述するときに,仕事の「入力」(前提となること)は何か,「出力」(結果)は何かを明確に書き分ける習慣を身につけると,自らが生み出す付加価値が明確になります.

 例えば,ある開発プロジェクトで作成された開発文書で,「要求仕様書」にも「アーキテクチャ設計書」にも,同じ「システム構成図」が記載されていたとします.どちらが,システム構成に関する情報として「入力」(前提となること)なのでしょうか? その工程で,新たに定義し決定した「出力」(結果)はどちらに書かれた情報でしょうか? もし,「要求仕様を取り決める工程」の後に「アーキテクチャ設計」を行う工程が位置するなら,「アーキテクチャ設計書」に書かれた「システム構成図」は,既に別の文書(要求仕様書)で決まっていること(事実であり,前提であり,「入力」)だということが,明示されなければなりません.あたかも,そこ(アーキテクチャ設計工程)で決定した事項のように書かれている「システム構成図」を,筆者は数多く見てきました.比較的上流のすべての工程で,システム構成をいちいち決定しているように受け取れる開発プロジェクトが,世の中にはたくさん存在しているようです(図2).

図2 同じ情報が複数個所に出現し,記述の「入力」と「出力」が区別できない


文書の中で,また,複数の関連する文書間でも,記述の「入力」と「出力」を明確に区別して記述しましょう.これは,自分が行うべき仕事を理解して整理することになります.このことを常に癖づけておくと,自動的に自分が「行うべきこと」の理解が深まり,そこから外れずに「行う」ようになるはずです.

組み込みキャッチアップ

お知らせ 一覧を見る

電子書籍の最新刊! FPGAマガジン No.12『ARMコアFPGA×Linux初体験』好評発売中

FPGAマガジン No.11『性能UP! アルゴリズム×手仕上げHDL』好評発売中! PDF版もあります

PICK UP用語

EV(電気自動車)

関連記事

EnOcean

関連記事

Android

関連記事

ニュース 一覧を見る
Tech Villageブログ

渡辺のぼるのロボコン・プロモータ日記

2年ぶりのブログ更新w

2016年10月 9日

Hamana Project

Hamana-8最終打ち上げ報告(その2)

2012年6月26日