テクニカルライティングのメモ

Just enough grammar (optional)

• 前置詞で重要なのは and, but, or
• 接続詞で重要なのは however, therefore, for example

Words

• 新しい用語を使う
  • 用語がすでに存在している場合は既存の説明にリンクしておく
  • 用語を紹介する時は定義から。たくさんある時は用語集にする
• 用語を一貫して使う
  • 文章全体で一貫して同じ用語を使う
  • 用語が長い時は最初に短縮形を用意する
• 略語(アクロニム)を適切に使う
  • 全部書いて略語を括弧で囲む。太字にする⇒Telekinetic Tactile Network (TTN)
  • 全部と略語を繰り返し使わない
  • 略語は元の用語が長い / 何度も出てくる時に使う
• 代名詞を明確にする
  • 名詞を使う前に代名詞を使わない
  • 代名詞は名詞の近くに置く。5単語くらい離れる時は名詞を繰り返し使う
  • 名詞と代名詞の間に別の名詞が入る時は名詞を繰り返し使う
  • it, they, them, and theirは混乱を引き起こす
  • this, thatは名詞に置き換えるか、this, thatの後に名詞を置く

Active voice vs. passive voice

• 能動態を使うようにする
  • 読者が受動態を能動態に変換する必要が無くなる
  • 受動態は考えが伝わりにくい 研究論文では受動態使われがち

Clear sentences

テクニカルライティングでは明確であることが一番大切

• be動詞, occur, happenは使わないようにする
• There is, There areを減らす
• 形容詞・副詞を最小限にする。曖昧な形容詞・副詞は定量的にする。

Short sentences

• １つの文には１つの考えを集中させる
• 長い文章はリストに変換する
  • 接続詞orを見つけたら箇条書きを検討
  • 文章中にリスト化できるものがあれば箇条書き/番号付きリストを検討
• 無駄に長い用語は短くする
  • ex) at this point in time ⇒ now
  • ex) determine the location of ⇒ find
  • ex) is able to ⇒ can
• 従属節を減らす
  • whichは非本質的(nonessential)thatは本質的(essential)で使う

Lists and tables

リスト
- 箇条書きは順番を並び替えても意味が変わらない。番号付きリストは変わる
- 埋め込みリスト(文章の中でリストを作る)は避ける
- パラレルなリストを作る(以下が一致しているとパラレル)
- 文法
- カテゴリ
- 文頭の大文字
- 句読点
- 番号付きリストは命令動詞で始める
- 文章の時以外は句読点も文頭の大文字も使わない

テーブル
- 各列にわかりやすい内容のヘッダーをつける
- セルにテキストを入れすぎないようにする
- 列内でパラレルになるように努める
- (パソコンで綺麗でもスマホでは崩れる可能性がある(その逆も))

共通して説明文を入れること。終わりには:をつける。followingを使うといい

Paragraphs

• 冒頭文は段落の重要点を記す
• 一つの段落は一つのトピックに絞る(前や次の段落のトピックを書かない)
• 長すぎず短すぎない段落にする
  • 1段落3~5文が目安(7文を超えると分けた方が良い)
  • 1文の段落がたくさんある時、まとめて1段落にするか、リストにする
• いい段落は次の3つの問いに答えている
  • What 読者に何を伝えようとしている？
  • Why 読者がこれを知ることが重要なのはなぜ？
  • How 読者はこの知識をどのように使うべき？あるいは、読者はどのように筆者の主張が真実と知るべき？

Audience

良い文章 = 聴衆(Audience)が仕事をするために必要な知識・スキル　－　聴衆の現在の知識・スキル

• 聴衆を定義する
  • 聴衆の役割を決める(エンジニア、研究者、学生など)
  • 役割が同じでも知識が同じではないが、知っている知識の近さが似る(心臓の専門家はプログラマーより耳の知識に詳しいが耳鼻科医師ほどではない)
  • 役割を決めて、何を知っているか、何を知らないか、何をもう一度紹介すべきか整理する
• 聴衆が学ぶ必要があることを決定する
  • 聴衆が目標を達成するために学ぶ必要がある事を全てリスト化する(場合によっては聴衆が実行する必要があることもある)
  • 特定の順番で学ばなければならないこともある(プログラム作成の前に、環境構築を学ぶ必要がある　など)
• 文章を聴衆に合わせる
  • 語彙と概念を聴衆に合わせる(略語など)
  • 専門家は新参者がわからないことを理解できてないことが多い(知識の呪い)
  • 簡単(Simple)な用語を使う
  • よくわからない例えをしない(プログラムの話を野球で例えない　など)
  • 各国でしか通じないイディオムは避ける(アメリカ⇒a piece of cake：朝飯前、イギリス⇒Bob's your uncle：万事OK）

Document

• 文書の範囲(scope)を決める。non-scopeも決めると尚良い
  • sope statemantを用意するといい
  • 範囲から外れた場合は再度scopeに集中するか、scope statementを考え直す
  • 文書をレビューする時はscope statementを満たさないものを削除(あるいは分岐)する
• 聴衆を決める
  • 聴衆を決めると必要な知識や経験を特定することができる(事前に読んでおくべき文書も)
• 重要なポイントを前もって決めておく
  • 文書の冒頭で読者の重要な問いに答えるようにしておく
  • 1ページ目が一番エネルギーも時間もかかる
  • 長い文書には概要(summary)をつける
• 聴衆のために書く
  • 聴衆を決める
    • ターゲットとなる聴衆は誰？
    • 読者の前提知識は？
    • 文書を読んだ後、読者は何を学んで何ができるようになっている必要がある？
  • 整理する
    • 聴衆の決定によって適切なアプローチができる(一部が知らない内容なら説明せずにリンクを貼る　など)
• トピックをセクションごとに分割する
  • 容器に岩⇒砂利⇒砂の順番に入れないと入らないように、岩(セクション)から決める必要がある
  • 砂利と岩の見分け方　2~5分程度トピックについて自分で話す、または自由に書いてみる 　(曖昧な表現で、聴衆が目標を達成するために必要なステップを順序ごとに表現すること) 　　　　⇒この時に出てきな曖昧なものがセクションになる

Punctuation

• コンマ(句点)
  • 句点は読点よりも短い休憩
  • リストを区切る時にも使う。A, B, C, and...の最後のコンマ(serial comma)はあったほうがいい
  • 条件は条件と結果の間に入れる(If~, then...)
  • コンマで挟むことで小さい定義や余談を入れることもできる
  • コンマを使用して2つの独立した内容を並べてはいけない
• セミコロン
  • セミコロンはピリオドと違い関連のある内容を統合する
  • セミコロン前後の文は文法的に完全でなければならない
  • セミコロン前後の文は順序が逆でも通じる
  • リストで区切る時はセミコロンではなくコンマを使う
  • セミコロンの直後に接続語(however, thereforeなど)を入れられる
• Em-Dashes
  • コンマよりも大きな停止を与える
  • 例文：C++ is a rich language—one requiring extensive experience to master.
  • ペアで２つ使うこともある
  • コンマの代わりにEm-Dashを使うこともできる。(使うタイミングはセンス)
• 括弧
  • 括弧は重要でない情報ということを示す
  • 括弧とピリオドの位置関係は、(～～.)と書き、～～(～～).と書く