意識のスコープを縮小せよ

意識のスコープ

　日本語による説明文の品質向上を目的として、IT技術者が直面するさまざまな文書事例からその問題点と改善策を検討する本連載、第3回は「意識のスコープを縮小せよ」というテーマでお届けしよう。

　「スコープ」と言うとIT技術者の間では「プログラム言語における変数のスコープ」という概念がよく知られている。要するに、ある変数がソースコードのどこからどこまでの範囲から「見える」かを示すのがスコープである。この意味での「スコープ」はできるだけ狭いほうがよい（図1）。スコープが広すぎると、その分、思いがけないところに影響を及ぼしてしまう可能性が高くなり、プログラムの保守性が下がるわけだ。

図1　スコープは狭い方がいい

　文書を書く場合も実はまったく同じことが言える。「スコープを狭くすること」を意識して書かれた文書は、読者がそれを解読しようとするときに、狭い範囲の情報だけ覚えておけばよいので楽なのだ。まずはよくない例として、以下の一文を考えてみよう。

例文1：必要に応じて設定ファイルsx.confを編集してからrestartsxコマンドを起動することにより、SXサービスを再起動することができます。

　短い文なので欠点が目立たないが、このような書き方はあまりよくない。なぜよくないのかを知るために、この文を前回説明した「ラベル付きステートメント構造」で書き直すと次のようになる。

【手順1】必要に応じて設定ファイルsx.confを編集します。

【手順2】restartsxコマンドを起動します。

【ゴール】SXサービスが再起動されます。

　「ゴール」のところは「目的」や「結果」「成果」と書いてもかまわないだろう。