SHOEISHA iD

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

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

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

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

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

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

 テクニカルライティングに役立つ(かもしれない)話をあれこれと書く連載。第7話は、解説するときはたとえ不正確ではあっても簡単な説明から始めようという話です。

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

はじめに

 テクニカルライティングでは、なんらかの技術を解説することが多いものです。そのとき、いっぺんに全てを説明しようとしていませんか? それをやってしまうと、一度に大量の情報を受け取った読み手は消化不良をおこしてしまいます。情報の奔流に溺れてしまうでしょう。最初は想定している読者にすっと受け取ってもらえるサイズの情報量から始めて、それからだんだんと情報を増やしていくような書き方をするとよいです。

 そういうちょっとずつ情報を増やしていく解説のやり方の1つとして、今回は簡単な話から初めてステップアップしていくというパターンを紹介しましょう。

簡単な話から難しい話へ
いっぺんに全てを語るな! 簡単な話から難しい話へステップアップ

対象読者

  • テクニカルな文章を書いている人/書かなきゃならなくなった人
  • その中でも、とくにソフトウェア開発に関わっている人

 テクニカルライティングの領域は広いですけど、この連載ではソフトウェア開発に関連した文書を主に想定しています。

解説とリファレンス

 本題に入る前に、ちょっと寄り道。「技術解説」と「リファレンスマニュアル」は、どちらもテクニカルライティングではありますが、想定読者が違います。

  • 解説:まだ分かっていない人に理解してもらう
  • リファレンス:もうだいたい分かっている人が参照する

 ここで話題にしている「いっぺんに全部を説明しても分からないよ」というのは、技術解説の場合です。リファレンスでは逆に、正確な話だけ網羅して書かれている方があちこちページをめくらなくて済んでありがたいのです。

 以下に「リファレンスマニュアル」の意味を紹介しておきます。IT用語辞典 e-Wordsからの引用です。

リファレンスマニュアル (reference manual)IT用語辞典 e-Wordsより

 製品に添付される文書の一種で、対象の機能や仕様などを網羅的に解説したもの。「マニュアル」を省略して単に「リファレンス」と呼ばれる場合が多い。

 構成要素や機能や仕様、使い方などを詳細に解説した文書で、基本的には最初から順番に読むものではなく、必要に応じて知りたい項目を参照するために用意されている。詳細な使い方を知りたい場合や、対応製品の開発を行なうために厳密な仕様を知りたい場合などに使われる。

 このようにリファレンスはすでにだいたい分かっている人が必要に応じて知りたい項目を読むものなので、まだ理解していない人が読むには難しいものなのです。プログラマーが渡された仕様書を理解しにくいと感じるとき、それはその仕様書に仕様の解説がなくてリファレンスだけになっているせいかもしれません。「仕様書は解説とリファレンスから構成されているべき」というのが私(=筆者)の持論ですが、その話はまた機会があれば。

 さて、それに対して技術解説は、その技術を知らない読者に理解してもらうために書きます。知らない話をいっぺんにまとめて突き付けられたのでは、理解するのは難しいでしょう。なんとか理解してもらいやすくする工夫が必要です。その工夫のひとつが、簡単な話から始めて難しい話へステップアップしていく書き方です。

会員登録無料すると、続きをお読みいただけます

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

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

メールバックナンバー

次のページ
まとめていっぺんに書かれると分からない

関連リンク

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

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

もっと読む

この記事の著者

biac(ばいあっく)

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

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

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

この記事をシェア

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

おすすめ

アクセスランキング

アクセスランキング

イベント

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

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

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

メールバックナンバー

アクセスランキング

アクセスランキング