加具留矢流余

かぐるやるよ

Google Technical Writing Part 1を読み始めた

英語で技術よりの文書が書けるようになりたくて、Google Technical WrtingのPart 1を読み始めた。

developers.google.com

内容は英語技術文書を書くためのエッセンスを詰め込んだものになっている。読んでいてあたりまえじゃん!って思ったが、実際に過去に自分が書いた文章を見ていると全然出来てなくて驚く。

今のところ「Technical Writing One」〜 「Short Sentence」まで読んだので各章のメモ。

Word(単語)

色々なトピックに関して触れていたので箇条書きで。

  • 文章内で単語の一貫性を保つ
  • 単語を明確に定義する
    • よく知られるものであれば単語の定義のリンクを貼る
    • そうでないなら明確に定義する。量が多いなら用語集を作る。
  • 略称を使う場合には初回だけ正式名称(略称)という表現を使う
  • そもそも略称を使うべきか判断する(長さと頻度を判断基準に)
  • 代名詞は混乱を招くので使用を控える
  • 代名詞を使うのであれば明確な場合にのみ使う

メモ

英語だけでなく日本語で書く場合にも使える普遍的な内容だと思う。一貫性、定義、略称は混乱のもとなので普段から気を付けたい。 代名詞は日本語だと英語に比べて使用頻度が低い気がするが気を付けるに越したことはないと思う。

Active Voice(能動態)

能動態と受動態どちらを使うべきかという話。可能な限り能動態を使うべきという結論だった。理由としては

  • 読者は暗黙的に脳内で能動態に変換している。
  • 能動態に比べて読みづらい。能動態のほうが直接的に表現している。
  • 短い
  • 主語が抜ける場合があって明瞭性に欠ける

メモ

なるほどという感じだった。英語力が低くて逃げの受動態を使っていたが、載ってる例などを見ていると能動態のほうが圧倒的にわかりやすい。

日本語の場合だとどうなんだろうと考えてみた。あまり普段から能動態と受動態を意識したことが無いが、やはり能動態で書いた方がわかりやすいことが多いのかなと思う。日本語は能動態、受動態に関わらず主語が抜けることがあるので、そこが注意するべき点ではないだろうか。

Clear Sentences(明快な文章)

あまり読み込めていないが主なトピックは以下の通り。

  • 強い動詞を使わない
  • Thereを使わない
  • あいまいな形容詞・副詞を使わない

強い動詞というのはhappenやoccurなどの普遍的で使いやすい単語を使うのではなくて、triggerやgenerateなどの使われる場面が限られている=情報量が多い動詞を使うべきと理解した。

メモ

強い動詞を使うという主張は理解しているが、語彙力が無くて普遍的な単語しか使えないという悲哀。Thereは長くて退屈だから使うなという主張のようだ。There文は単純に後ろにある文章を前に持ってくるか、主語をYouに変えて文章書き直せば簡単に直せるよという有り難いアドバイスが書いてあるので活用しようと思う。

Short Sentences(短い文章)

短いコードが読みやすいようにドキュメントも短く簡潔にという内容。

  • 1文には一つのアイディアに留める
  • andで繋いで長くなった文章は、リストに切り出すことを考える。
  • 無駄に長い言い回しを避ける。
  • whichとthatの使い分け(関係代名詞)

メモ

言葉にすれば簡単だが実践するのは難易度が高い内容だと思う。気がつけば長文が出来上がっている。この章の内容も日本語でも積極的に使いたい内容だった。特に日本語は無駄に長い言い回しをするのが得意な言語だと思うので、そこは直していきたい。

whichとthatは完全に同じ意味だと思っていたがそうではないらしい。少なくともアメリカでは。whichは無くても文意が通る場合に使い、thatは無いと文意が通らない場合に使うとのこと。豆知識を得てしまった。

まとめ

まだ前半しか読んでないが有意義な内容だった。長くてやってらんねーよ!という方はトピックを訳している記事があるのでそちらだけでも。

qiita.com