テクニカルライティング続き

リストとテーブル

　優れたリストは、技術的な混沌を秩序あるものに変えることができます。技術系の読者は概してリストを好む。したがって、文章を書くときには、散文をリストに変換するようにする。

正しいリストのタイプを選ぶ

テクニカルライティングの主流は、次のようなリストです：

箇条書きリスト
番号付きリスト

順序のない項目には箇条書きリストを使用し、順序のある項目には番号付きリストを使用する。

箇条書きリストの項目を並べ替えても、リストの意味は変わりません。
番号付きリストの項目を並べ替えると、リストの意味が変わります。

リスト項目を並列に保つ

効果的なリストと欠陥のあるリストの違いは何でしょう？
効果的なリストは並列であり、欠陥のあるリストは非並列である傾向があります。並列リスト内のすべての項目は同じものに「属している」ように見えます。つまり、並列リスト内のすべての項目は、以下のパラメータに沿って一致します：

句読点、文法、論理カテゴリー、大文字小文字

便利なテーブルの作成

　分析的な頭脳はテーブルを好む傾向がある。複数の段落と1つの表を含むページがあると、エンジニアの目は表の方にいく。

表を作成する際には、以下のガイドラインを考慮しましょう：

各列に意味のあるヘッダーを付ける。読者に各列の内容を推測させない。
表のセルにテキストを入れすぎない。表のセルに2つ以上の文章を入れる場合は、その情報が他の形式の方がふさわしいのではないかと自問する。
異なる列には異なるタイプのデータを入れることができますが、個々の列の中では並列性を保つように努めましょう。例えば、ある表の列のセルに、数値データと有名なサーカス団員が混在しない。

各リストと表を紹介する

　各リストや表を紹介する際には、そのリストや表が何を表しているかを読者に伝える文章を入れる。言い換えれば、リストや表に文脈を与える。

段落

このユニットでは、まとまりのある段落を作るためのガイドラインをいくつか紹介します。

素晴らしい冒頭文を書く

　冒頭の一文は、どの段落でも最も重要な一文です。忙しい読者は冒頭の文章に集中し、その後の文章を読み飛ばしてしまうことがある。そのため、冒頭文にエネルギーを集中させる。良い冒頭文は、段落の中心点を確立する。

テクニカルライティングで素晴らしい冒頭文を書くコツ

1. 最初に要点（主文）を明確に述べる

　テクニカルライティングでは、段落や文書の冒頭で伝えたい要点を簡潔に示すことが基本です。読者は理由や経緯よりも「何が重要なのか」を最初に知りたいので、結論や主題を冒頭に配置する。

2. 読者目線を意識する

　誰が読むのかを想定し、その読者が知りたい情報や背景知識に合わせて、分かりやすく、誤解のない表現を心がける。

3. 簡潔で具体的な表現を使う

　曖昧な言葉や冗長な説明を避け、強い動詞や明確な用語を選びます。1文1メッセージを意識し、長い説明はリストや表で整理します。

4. テンプレートを活用する

　解説系の冒頭文なら「～とは、●●のことです」「～でポイントになるのが、●●です」など、結論を先に述べるテンプレートが有効です

例：素晴らしい冒頭文のパターン

「○○とは、□□を実現するための技術です。」
「このドキュメントでは、△△の設定手順について解説します。」
「安全に作業を行うためには、以下の注意点を守る必要があります。」

ポイントまとめ

要点を冒頭に明確に示す
読者目線・簡潔さ・具体性を重視
テンプレートや定型表現を活用する

各段落を1つのトピックに絞る

　段落は独立した論理の単位を表すこと。各段落は現在のトピックに限定する。未来のトピックで何が起こるか、過去のトピックで何が起こったかを記述しない。推敲するときは、現在のトピックに直接関係しない文章は容赦なく削除する。（または別の段落に移す）。

段落は長すぎず、短すぎず

　長い段落は視覚的に威圧的です。長すぎる段落は、読者が無視する恐ろしい「テキストの壁」を形成します。読者は一般的に3～5文の段落は歓迎しますが、7文以上の段落は避けます。校閲の際には、長すぎる段落を2つの段落に分けることを検討する。

　逆に、段落を短くしすぎないようにする。文書に1文の段落がたくさんある場合は、構成に欠陥があります。これらの1文の段落を、まとまりのある複数の文の段落にまとめるか、場合によってはリストにまとめる方法を模索する。

何を、なぜ、どのように答えるか

良い段落は次の3つの質問に答えています：

読者に何を伝えようとしているのか？
なぜ読者がそれを知ることが重要なのか？
読者はその知識をどのように使うべきか？あるいは、読者はあなたの主張が真実であることをどのように知るべきか？

読者

皆さんはおそらく数学に慣れていると考えています。したがって、この単元は方程式から始まります：

良いドキュメント＝読者があるタスクを行うために必要な知識とスキル – 読者の現在の知識とスキル

言い換えれば、読者が必要としているがまだ持っていない情報を、あなたの文書が提供できるようにすることです。そこで、このユニットでは次のような方法を説明します：

読者を定義する。
読者が何を学ぶ必要があるかを判断する。
文書を読者に合わせる。

読者を定義する

　真摯なドキュメンテーションの努力は、読者を定義することにかなりの時間とエネルギーを費やす。このような取り組みには、調査、ユーザーエクスペリエンス調査、フォーカスグループ、ドキュメンテーションのテストなどが含まれるかもしれません。おそらくあなたにはそこまでの時間はないでしょうから、このユニットではよりシンプルなアプローチをとります。

読者の役割を特定することから始める。役割の例としては

ソフトウェアエンジニア
技術的な、非エンジニアの役割（技術プログラムマネージャーなど）
科学者
科学分野の専門家（医師など）
工学部の大学生
工学系大学院生
非技術職

　私たちは、非技術的な職務に就いている多くの人々が、優れた技術的・数学的スキルを持っていることを喜んで評価する。しかし、役割分担は読者を定義する上で不可欠な第一次近似値であることに変わりはありません。同じ役割の人たちは、一般的に特定の基本的なスキルや知識を共有している。例えば

ほとんどのソフトウェアエンジニアは、一般的なソートアルゴリズム、ビッグO記法、少なくとも1つのプログラミング言語を知っている。したがって、ソフトウェアエンジニアがO(n)の意味を知っていることは頼りになりますが、非技術職がO(n)を知っていることは期待できない。
医師を対象とした研究報告書は、一般読者を対象とした同じ研究についての新聞記事とは全く違って見えるはずです。
教授が大学院生に新しい機械学習のアプローチを説明するのと、学部1年生に説明するのとでは、異なる。

　同じ役割の全員がまったく同じ知識を共有していれば、文章を書くのはとても簡単になる。残念ながら、同じ役割内の知識はすぐに分かれる。アマルはPythonの専門家、シャロンの専門はC++、マイカの専門はJavaだ。カーラはLinuxが大好きだが、デビッドはiOSしか知らない。

役割だけでは、読者を定義するには不十分だ。つまり、読者が知識に近いことも考慮しなければならない。プロジェクト・フロムバスのソフトウェア・エンジニアは、関連するプロジェクト・ディンガスについては何か知っているが、関係のないプロジェクト・カランボラについては何も知らない。平均的な心臓専門医は、平均的なソフトウェア・エンジニアよりは耳の問題について知っているが、聴覚専門医よりははるかに少ない。

時間はまた、近さにも影響する。たとえば、ほとんどすべてのソフトウェア・エンジニアは微積分を学んだ。しかし、ほとんどのソフトウェア・エンジニアは仕事で微積分を使わないので、微積分の知識は次第に薄れていく。逆に、経験豊富なエンジニアは、通常、同じプロジェクトの新人エンジニアよりも、現在のプロジェクトについてはるかに多くのことを知っている。