Technical Writing One introductionがよかったので読書メモを書きました
まとまった文章を書く機会が増えたので、Googleの公開しているTechnical Writing One introduction（以下、One introduction）を読みました。この記事はその読書メモをまとめたものです。
Googleが公開する学生向け（For Student)のコンテンツは、Technical Writing Two introduction（以下、Two introduction）もあります。 Two introductionは発展的・ソフトウェアエンジニアリングにより特化した内容ですので、より汎用的なOne introductionの内容を読みました。
なお、これらのコンテンツはすべて英語で書かれていますので、当然英語の文章を前提とした説明になってます。しかし、大半は日本語の文章に応用できる内容でした。
この記事を書くにあたって、次の日本語の要約記事をたいへん参考にさせていただきました。
また、直接的な関係はありませんが、Amazonの文書構成術の記事にも共通するものがありました。
目次
One introductionは次のページにより構成されています（強調は筆者）。
- Introduction (3 min)
- Just enough grammar (optional) (10 min)
- Words (10 min)
- Active voice (15 min)
- Clear sentences (10 min)
- Short sentences (20 min)
- Lists and tables (15 min)
- Paragraphs (10 min)
- Audience (10 min)
- Documents (10 min)
- Punctuation (optional) (5 min)
- Markdown (variable)
- Summary (1 min)
この記事では太字にしているページから、要点を箇条書きで取り上げます。
Word
- 新しい用語を定義する
- 用語を統一する
- 頭字語を使う
- 頭字語は、文章の中で最初に使うとき省略しない表記で書く
- 省略しない語（頭字語）を太字にする
- 例）Telekinetic Tactile Network（TTN）
- 短かすぎる頭字語は、読者が解釈するのに時間がかかるので注意する
Active Voice
- 能動態と受動態を区別する
- 受動態は主語（誰が）を省略できる
- よい技術文書がは、「誰が」・「何を」・「誰（何）に」が明確である
- 能動態を使用した方が良い
- 読者は受動態を能動態に変換して解釈するので、手間がかかる
Clear sentences
- 強い動詞を使う
- 強い動詞=他動詞、弱い動詞=自動詞ということ？
- 特定の形容詞は使わない
- とても速い → 225-250%速い
Short sentences
- ひとつのアイデアに各文を集中する
- 長い文はリストに分割する
- 冗長な言いまわしをしない
Lists and tables
- リストには3種類ある
- 順序なしリスト（bulleted lists）
- 並び替えて意味がかわらない
- 順序ありリスト（numbered lists）
- 並び替えて意味がかわる
- 埋め込みリスト（embedded lists）
- 手順のようなもの？順序なしリスト、順序ありリストに変換するとよい？
- 順序なしリスト（bulleted lists）
Paragraphs
- パラグラフの書き出しが重要
- 忙しい読者は読み飛ばすため、書き出しに中心となる話題を書く
- ひとつのトピック（主題？)に各パラグラフを集中する
- 読者が歓迎するパラグラフの流さは3-5文ほど
- パラグラフは次の3つ要素で構成するとよい
- 何を読者に伝えたいか？
- それを知ることが読者にとってなぜ重要なのか？
- 読者はその知識をどのように使うべきか？
Audience
- 良いドキュメント = 読者が知る必要のある知識・スキル - 読者が知っている知識・スキル
- 読者がすでに知っていることを説明しない
- 熟練者が書き手である場合は、初心者が知らないことを簡単に忘れるので注意が必要
Documents
- 良いドキュメントには対象読者・スコープが書かれている
- より良いドキュメントには説明しないことが書いてある
- プロの書き手は、読者が2ページを開く確立をあげるために、1ページ目に考慮可能なだけの労力をかける
- 主題をそれを構成するセンテンスに分け、細分化して文章を書く
まとめ
基本的には文章を書く上で知っていた方がよいことを簡潔にまとめられていました（Clear sentencesのページはあまり意識してないことが多かったです）。
読書メモを書くときに、意訳してしまった点や、十分に考察しないまま書き連ねた箇所がありました。 文意を正しく知りたいという方は原文を読んでください。
