SHOEISHA iD

※旧SEメンバーシップ会員の方は、同じ登録情報(メールアドレス&パスワード)でログインいただけます

DeveloperZine(デベロッパージン)- エンジニアの意思決定を支える技術情報メディア ProductZine

CodeZine編集部では、現場で活躍するデベロッパーをスターにするためのカンファレンス「Developers Summit」や、エンジニアの生きざまをブーストするためのイベント「Developers Boost」など、さまざまなカンファレンスを企画・運営しています。

テクニカルライティング作法・外伝

「大雑把な分割から始めよう!」~ソフトウェア開発者に贈るテクニカルライティングの極意

テクニカルライティング作法・外伝 第8回

説明に不要なアイテムを削る

 例えば、今はパソコンが演算する仕組みを説明したいのだとしましょう。その場合は、説明に必要のない電源だとかCPUファンだとかグラフィックカードだとかは省略してしまえばいいのです。補助記憶装置も、HDD/SSDは説明に必要でしょうが、それ以外の補助記憶装置は省略できるでしょう。

 すると、演算する仕組みを説明するときは、次のようなリストを提示すれば済みます。

  • CPU
  • メモリーカード(主記憶装置)
  • HDD/SSD(補助記憶装置)

 アイテムが10個から3個に減って、すっと頭に入る分量になりました。

 ちなみに、演算する仕組みを実際に説明するときには、次のリストのように、なんとなく役割が分かるような呼び方に置き換えて、簡単な説明も付けておくといいでしょう。

  • 中央演算処理装置(CPU):演算を実行します
  • 主記憶装置:CPUに隣接したメモリー。高速に動作します
  • 補助記憶装置:ハードディスクなど。低速だけど大容量です

アイテムを階層化する

 階層化することで、それぞれの階層に含まれるアイテムの数が減ります。そうすると頭に入りやすくなります。

 階層化するとは、なんらかの基準を設けてアイテムをグループ化していくことです。パソコンの構造の例では、「CPU」と「CPUファン」と「メモリーカード(主記憶装置)」はマザーボードの上に載っています。実際にひとつにまとまっているものという基準で、これらをひとつの「マザーボード」というくくりにまとめられます。同様に、「電源」はケースと一体になって売られていることが多いので、「ケース」というくくりにまとめてよいでしょう。あるいは、「HDD/SSD(補助記憶装置)」と「DVD/BDドライブ(補助記憶装置)」と「メモリーカードリーダー/ライター(補助記憶装置)」は、いずれも補助記憶装置です。どんな役割の装置かという基準で、これらは「補助記憶装置」というくくりにまとめられます。

 そうやってまとめると、一番上の階層に含まれるアイテムは10個だったものが次のように4個に減ります。

  • ケース
  • マザーボード
  • グラフィックカード[オプション]
  • 補助記憶装置

 ここで、説明するのに「グラフィックカード[オプション]」は挙げなくてもよいのであれば、先に解説したように省略してしまいましょう。すると次のように3アイテムとなって、頭に入りやすい個数になりました。

  • ケース
  • マザーボード
  • 補助記憶装置

 そして、実際に説明していく中で、「マザーボードは、マザーボード本体とCPUとメモリーカードから成っていて…」といったように下部の階層を説明していきます。パソコンの構造の場合、アイテムの最終的な階層構造は次のようになりますね。

  • ケース
    • ケース本体
    • 電源
  • マザーボード
    • マザーボード本体
    • CPU
    • CPUファン
    • メモリーカード(主記憶装置)
  • 補助記憶装置
    • HDD/SSD
    • DVD/BDドライブ[オプション]
    • メモリーカードリーダー/ライター[オプション]

 大事なのは、いっぺんに提示するアイテムの数を3つくらい、せいぜい5~6個にとどめることです。上の例では、まず第1階層として3個のアイテム(=ケース/マザーボード/補助記憶装置)を提示して説明します。それから第2階層に進んで、2個/4個/3個のアイテムを順に提示していきます。階層化する基準(=グループ化する基準)がいいかげんだったり、今回の例のように複数の基準をゴッチャにしたりといった無理をしてでも、いっぺんに提示するアイテムの数を減らしたほうが理解しやすくなるはずです。

まとめ

 テクニカルライティングの目的によっては、例えば特許の申請のように、すべての構成要素とその説明をいっぺんに提示するという書き方が求められることもあります。そのような縛りのない技術解説などでは、理解のしやすさを優先して、いっぺんに提示するアイテムの数を3つくらい、多くても5~6個までにとどめるようにしましょう。その方法として、説明に不要なアイテムを削ることと、アイテムを階層化して提示するやり方を紹介しました。

関連リンク

この記事は参考になりましたか?

連載通知を行うには会員登録(無料)が必要です。
既に会員の方はを行ってください。
テクニカルライティング作法・外伝 連載記事一覧

もっと読む

この記事の著者

biac(ばいあっく)

HONDA R&Dで自動車の設計をやっていた機械屋さんが、技術の進化スピードに魅かれてプログラマーに。以来30年ほど、より良いコードをどうやったら作れるか、模索の人生。わんくま同盟の勉強会(名古屋)で、よく喋ってたりする。2014/10~2019/6 Microsoft MVP (Windows Devel...

※プロフィールは、執筆時点、または直近の記事の寄稿時点での内容です

この記事は参考になりましたか?

この記事をシェア

CodeZine(コードジン)
https://codezine.jp/article/detail/11693 2019/09/20 14:00

イベント

CodeZine編集部では、現場で活躍するデベロッパーをスターにするためのカンファレンス「Developers Summit」や、エンジニアの生きざまをブーストするためのイベント「Developers Boost」など、さまざまなカンファレンスを企画・運営しています。

新規会員登録無料のご案内

  • ・全ての過去記事が閲覧できます
  • ・会員限定メルマガを受信できます

メールバックナンバー