2020/12/06に書いていたメモ。当時は学部の4年で卒論を書いていた頃で、卒論をきっかけに技術文章を書くことに興味をもって調べていて見つけた動画をメモしていたのだろう。ブログ記事を書いたり、あとは雑誌の記事を書いたりするときにも参考にしていたもので、まとまった文章を書く必要に迫られたら見返したくなる。

以降は箇条書きであくまでメモなので、詳細は当然動画を見ていただけるとよくて、動画を見返すためのインデックスとして書き出している。

以下は、Youtubeに公開されている動画 (15) 技術文書の書き方 ・ゲスト：Web+DB Press稲尾さん - YouTube を聞いた内容である。

動画内で紹介されている書籍

日本語で文章を書くテクニック

一文単位のテクニック(24:00)

一文の中で語順をどう並べればよいか(24:30)

  • 修飾子の並び順は、修飾子の長いものほど前に並べる。
  • 読点の打ち方(28:45)
    • 長い修飾語が2つ以上あるときその境界に点を打つ。
    • 修飾子の並び順が逆順の場合は点を打つ。
  • 指示代名詞を多用しない。仕方ない場合は指示連体詞を使う。(35:10)
  • 難しい一文を書かない。長くしない。(37:15)

段落をどう分けるか(38:18)

  • １つの段落では１つのトピック。
    • 一文目は概要。
    • 二分目以降は詳細の説明。
    • 一文目に概要を書かない場合でも、1つの段落で1つのトピックに限定すべき。
  • 一段落の粒度は見出しの粒度に依存する。
    • 小見出しを使って見出しの粒度を調整すると、段落の粒度も調整できる。
    • 階層が深くなりすぎるときは章を分割して繰り上げる。(３階層くらいまで)

全体構成(見出し構成)

  • ロジカルシンキングの本を読む
    • 話の漏れ, 重複を防ぐ
    • 話の飛びをなくす
  • 対象読者のうち、最も前提知識のない人がどの階層の見出しまでを読んでも話がわかるようにする。
    • 固有名詞だけの見出しは良くない。固有名詞がわからなくても良いように説明的にする。
    • 見出しだけで答えまでわかるようにする。「○○の特徴」という見出しがあるとき、その下の小見出しはその答えを列挙する形式にしておくとよい。
    • 読解力が必要な見出しは避けるべき。
    • 列挙するだけの見出しはよくないので説明的にする。「変数と定数」よりも「変数と定数による値の管理」のほうがいい。
  • ページあたりの見出し
    • 書籍では2見出し/ページ, 雑誌では4見出し/ページ (どちらも大見出しや小見出しをすべてカウントして)
    • 上記から一段落の長さも逆算される。
  • 見出し数は下の階層の見出しほど多くなるようにする。(下の階層ほど詳細を説明しているから)
  • 見出しの文字列の長さも、下の階層の見出しほど長くなるようにする。(下の階層ほど詳細を説明しているから)
  • 書き始める前に見出し構成を考えるほうがいい。後で変えるのはいいけど、書き出す前に考えよう。

技術文章特有のテクニック

  • 専門用語を統一
  • 読者がソースコードや図を読み飛ばしても大意は読み取れるようにする。「次のコードは○○をしています」といった文章(トピックセンテンス的に)用意しておく
  • どこまで説明するかは割ける分量による。分量があれば変数とは、定数とはなども細かく
  • なんとなくでも説明する。x「〇〇を用いて」o「〇〇という最適化手法を用いて」
  • 種別も明記する。メソッドなのかクラスなのかインスタンスなのか要素なのか。

その他のテクニック

  • 事例から得られたノウハウを説明するとき、ノウハウが主題なら具体例よりもノウハウに主眼を置くべき。
  • テーマと対象読者を定めるのは大事。
  • 推敲で1割削ると良い。
    • 冗長な部分を削る
      • とても, 非常に, は冗長なので削る
      • することができます, してしまう といった表現を削る
    • 推敲するときの方法
      • 一晩寝かす
      • 読む媒体を変える
      • 音声読み上げさせると気づく
      • 朗読する