トップ > イベント参加 > 『merpay Tech Talk ~ 伝わる技術文書の書き方 ~』に参加したので学んだことをまとめる

『merpay Tech Talk ~ 伝わる技術文書の書き方 ~』に参加したので学んだことをまとめる

イベント参加 技術文章

『merpay Tech Talk ~ 伝わる技術文書の書き方 ~』という、メルペイ主催の技術イベントがあったので学んだことをまとめたいと思います。

mercari.connpass.com

イベントの内容

以下のような内容になっていました。

  1. オープニングトーク
  2. 柴田芳樹 さん（メルペイ Software Engineer）発表
    • 『merpay Tech Talk ~ 伝わる技術文書の書き方 ~』
  3. ひつじ (mhidaka) さん（メルペイ Experts team）発表
    • 『今すぐテクニカルライティングが必要になったときの転ばない杖』
  4. tenntenn さん（メルペイ Experts team）発表
    • 『実践！テクニカルライティング』
  5. わいわい質問タイム
    • 発表者同士の質問やイベント参加者からの質問とその回答
  6. 公開 処刑 レビュータイム

※資料公開があったらあとでリンク付けます。

学んだこと

技術文章の分類

文章には以下の分類がある。（by 柴田さん）

  • 理解した技術のまとめ
  • 新たな技術のまとめ
  • 自分で考えた手法・技術のまとめ
  • プロセス（プラクティス）の改善・導入
  • 自分の考え（心得など）を伝えたもの
  • 書籍紹介

特に理解した技術のまとめでは以下のように細分化される。

  • 多くの人にとっては既知かもだが、自分にとっては新たな理解であるもの
  • 技術は新しくないが、多くの人がきちんと理解してないかもしれないもの

文章を構成する時の注意点

  • 導入文があると読者にメンタルモデルが出来るので読みやすくなる
    • 「はじめに」、「目標規定文」、「想定読者の説明」など
  • 文章を書く時のフレームワーク（柴田さん作）
    • 技術系
      1. 技術を導入する前の課題の説明
      2. その課題を解決するために導入した技術の概要
      3. どのように導入したかの説明
      4. 導入後の課題の解決状況
      5. 残された課題と今後の対応予定
    • 改善活動系
      1. あるべき姿の説明
      2. 現状把握と分析
      3. 対策の説明と実施
      4. 対策の効果の説明
      5. 残された課題と今後の対応
  • 文章書いたら読んでもらえる思ってはいけない
    • 「読者は筆者が思った通りには行動しない」
    • 面白いと思ってもらえるように努力する
    • イラストや表を使って読者をひきつける努力をする
  • 結論は先に説明する
  • 不要な情報は削減する
  • 結論に意見を書く
    • 意見を書くことで追体験につながる
  • 文章の流れ
    1. 文章の目的を考える
      • 目標規定文を記載する
    2. 見出しをざっくり考える
      • 章レベルで
    3. ネタを厳選する
      • 考えた見出しに合うコード片などを用意する
    4. 見出しをしっかり考える
      • 節レベルで主張したいことを簡単に書き下す
    5. ネタが見出しに合っているか考える
      • コードに過不足がないかチェック！
    6. 書く
  • うまく書けない場合
    • うまく書けない項目は飛ばす
      • 飛ばすと不要だったってなる場合も
    • 雑でもいいので箇条書きする
      • コードでもいい
    • 誰かに話してみる
    • いったん諦める
      • 別の作業をする
  • めっちゃ書いちゃう場合
    • 一旦最後まで書いてみる
    • 冗長な表現がないか見直す
    • バックアップを取った上で思い切って消しちゃう
    • コードを短くする
      • 文脈で分かるところや例外処理は省略
  • 「まずは」みたいな表現は書き始めなどで自身がない時に書きがち
    • 書いてもいいけど、あとで見直して消す

文章の表現に関する注意点

  • 表記ゆれは避ける
  • 漢字表記とひらがな表記の使い分け
    • 迷ったら用語辞典で調べる
      • 朝日新聞の用語の手引
      • 読売新聞 用字用語の手引
      • 講談社校閲局編 日本語の正しい表記と用語の辞典
      • NHK 漢字表記辞典
  • 正しい日本語を使用する
    • NHKことばのハンドブックを参考にする
  • 文章の見やすさに気を付ける
    • 半角丸括弧 () ではなく、全角丸括弧 （） を使うなど
  • 冗長な表現は避ける
    • 例1：「出来るのであれば」→「出来れば」
    • 例2：「することなく」→「せずに」
    • 例3：「行うことが出来ます」→「行えます」
  • 誤字脱字は避ける
  • 技術用語は正しい用語を使用する
    • チーム固有の用語ではないか？
    • 英語表記である必要性のないものはないか？
      • 例：「microservice」→「マイクロサービス」
  • 正確性と分かりやすさのバランスを取る
    • 正確でも情報量が多いと分かりにくくなる
  • 主語は省かない
    • タイトルを書いた後が省略されがち
    • 筆者が自明だと考えているとき、読者は置き去りになる
  • 受動態は避ける
    • 受動態は主体が曖昧になる
  • 誤解が発生しない表現にする
    • 比喩表現は伝わりにくい
    • 弱い動詞、複数の意味のある動詞を使用しない
  • 事実は可能な限り簡潔に書く
    • 事実と意見を混同しない
  • 意見は誰のものか明らかにする
    • 意見は事実の裏付けをもって主張する
  • 口語と文語を使い分ける
  • 1文は簡潔に書く
    • 主語と述語で文章が成り立っているか？
  • 論拠をあげる
    • 論拠は自分の主張が尤もことを補う武器
  • 正しい情報を伝える
    • 推測や感想を混ぜない
  • 意見は「私は～と思う」で表現する
  • 参考文献はアクセス日時なども併せて記述する
  • 固有名詞は正式名称を用いる
  • ローマ数字と漢数字の使い分け
    • 数えられるものは数字、数えられないものは漢数字で表現する
      • 例：りんご3つ、三角形
  • 最近の流行りは1段落2～3行
  • 「～と思います」ではなく、言い切ることで共感されやすい

文章をレビューするときの注意点

  • 自己レビューする時
    • 自分で読んで理解できますか？
    • 正しい用語を使っていますか？
    • 技術的に間違っていませんか？
  • チーム内レビュー
    • 自己レビューより見落としに気付ける
      • しかし、チーム固有の技術的説明など第三者視点でレビュー出来ない可能性がある
    • 第三者レビューして貰うまでに軽微な部分を見て貰う感じ
  • 第三者レビュー
    • 扱ってる技術をよく知らない人からのレビュー
      • 読んで理解できる内容か確認してもらう
    • 扱ってる技術をよく知っている人からのレビュー
      • 技術的に間違っていないか確認してもらう
  • 耳で聞いてみる
    • OSの読み上げ機能を使ってみる
    • 耳で聞いてみて頭に入ってこない文章は読んでも分からない
  • 自動化ツールを使ってみる
  • Google ドキュメントを使う
    • コメント機能の活用
    • バージョン機能の活用
  • 自分の癖みたいな表現は自己レビューが困難
    • 他人に見て貰う
    • スクリプトで表記ゆれなどを検知する
    • 書き味として残してみる

所感

『『『文章書いたら読んでもらえる思ってはいけない』』』

これがめちゃめちゃ痛いですね。終わってからずっと頭に残っています。

これ、技術ブログや書籍執筆に限らず普段のメールやチャットでの会話でも同じことが言えるのではないかと思いました。

それから今回のイベントの発表者の方々は国語的なテクニックを書籍などから学び、それを何度も実践するということとLintツールなどを駆使して出来ないことは割り切るという使い分けが上手く出来る人達なんだなと感じました。

textlint や RedPen 何かはさっそく使ってみたいですね。