SHOEISHA iD

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

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

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

「起承転結はあるんだよ」~ソフトウェア開発者に贈るテクニカルライティングの極意

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

  • X ポスト
  • このエントリーをはてなブックマークに追加

テクニカルライティングでの起承転結

テクニカルライティングに当てはめた「起承転結」
テクニカルライティングに当てはめた「起承転結」

 さて、テクニカルライティングの構成に起承転結を当てはめると、次のようになるでしょう。

  • 「起」:話題と結論を提示します
  • 「承」:「起」を受けて、結論にそった話を展開していきます
  • 「転」:一転して、結論に反するような話を展開します
  • 「結」:「承」と「転」をまとめて、話を「起」の結論に戻します

 簡単な話題なら、「起承」だけで終わってしまうこともあるでしょう。それなら無理に「転結」を付ける必要はありません。

 結論と違う話も読者に伝えたいときは、ひととおり結論にそった話を展開してから、「転」の位置でします。結論にそった話の中にそれと反する話を細切れに入れてしまうと、読者は混乱してしまうでしょう。また、読者は「起」を受けてその詳細を知りたいと思って読み進めますから、「承」の前に「転」を置いてしまうと読者は焦れてしまうでしょう。

 「転」を置いたときは、最後に「結」で話を元に戻します。そうしないと、読者は「結論はなんだったっけ?」と不安になってしまいます。「転」があって「結」がないと、落ち着きません。まさにオチが付かなくて、尻切れトンボになっちゃいます。また、長い文章のときは、「転」がなくても「結」を置いたほうがやはり落ち着きます。

 ちなみに、この記事には「転」(=テクニカルライティングで起承転結は使えないといった話)がありませんから、「起承結」です。

 最後に、いくつか例文を挙げておきましょう。

「起承」の例

 例えば、APIの使い方の解説で、どんなときでも通用する話なら「起承」だけで十分です。次は、C#でのプログラミングの話題です。

  • タイトル:「awaitを含むコードブロックを排他ロックするには?」
  • 「起」:awaitを含むコードブロックを排他ロックするには、SemaphoreSlimクラスなどを使う。
  • 「承」:awaitした後のコードは、別スレッドで実行される可能性がある。awaitを含むコードブロックを排他ロックするには、別スレッドからロックを解放しても問題のないSemaphoreSlimクラスなどを使う。実際のコード例を示すと……

「起承転結」の例

 何かを選択するレポートをまとめるとき、比較表を書いて「これが一番いい」とやりますが、比較表とは違う観点から「いや、こっちの方がいいんだ」と言う人が出てくるものです。「転」を置いて、そういう主張に対する検討を入れます。次は、プロジェクトに採用するプログラミング言語の調査報告書の例です。

  • タイトル:「★★プロジェクトの開発言語選定の件」
  • 「起」:本プロジェクトには◯◯言語が適している
  • 「承」:以下の観点で比較を行った。……
    比較表は次のようになる。……
  • 「転」:ところで、□□の観点から△△言語がよいという意見もあるが、□□の観点は本プロジェクトにおいては……
  • 「結」:やはり、◯◯言語が適している

 APIの使い方の解説でも、それが通用しない場合があるなら「転」を置いて説明します。通用しない場合の説明(=結論とは違う話)を先に長々とやってしまうと、それは読者がまず知りたいと思っている情報ではないので、読み進めるのが苦痛になってしまいます。次は、C#でのプログラミングの話題です。

  • タイトル:「テキストファイルを読み込むには?」
  • 「起」:テキストファイルの全体を読み込むには、StreamReaderクラスのReadToEndAsyncメソッドを使う。
  • 「承」:ReadToEndAsyncメソッドの使い方は……
  • 「転」:ただし、メインスレッドをブロックしても構わないサーバープログラムなどでは、FileクラスのReadAllTextメソッドが使える。詳しくは◯◯を参照のこと。
  • 「結」:テキストファイルの全体を非同期的に読み込むには、ReadToEndAsyncメソッドを使う。

まとめ

 テクニカルライティングは結論を先に書きます。そこで、「起承転結」の「結」を「結論」のことだと誤解して「起承転結はテクニカルライティングに向いていない」と主張されることがあります。しかしそんなことはありません。「起」にも結論を書けばよいのです。テクニカルライティングでも「起承転結」構成は役立ちます。

関連リンク

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

  • X ポスト
  • このエントリーをはてなブックマークに追加
テクニカルライティング作法・外伝 連載記事一覧

もっと読む

この記事の著者

biac(ばいあっく)

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

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

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

この記事をシェア

  • X ポスト
  • このエントリーをはてなブックマークに追加
CodeZine(コードジン)
https://codezine.jp/article/detail/11332 2019/02/01 11:00

おすすめ

アクセスランキング

アクセスランキング

イベント

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

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

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

メールバックナンバー

アクセスランキング

アクセスランキング