はじめに
こんにちは。oka-shi@技術ブログ初心者です。
先日、merpayさんのオンライン勉強会『伝わる技術文書を書く』 に参加してきたので、自分用に備忘録を残します。
動画はYouTubeに公開されていますので、興味がありましたらご参照ください。
動画の概要
- merpay Tech Talk ~伝わる技術文書の書き方~
https://www.youtube.com/watch?v=GvjScPO3OcA&feature=youtu.be - こんな方におすすめ
- 技術発信したいけど自信がない方
- 技術発信をより伝わるものにしたい方
- アドベントカレンダーで何か書かなければいけない方
- 書籍を執筆したい方
- 目次
- 伝わる技術文書の書き方
- 外部公開の分類
- 細かな言葉の注意点
- レビュー
- 「はじめに」の重要性
- フレームワーク
- 今すぐテクニカルライディングが必要になったときの転ばない杖
- 対象読者と期待値のコントロール
- 正確性と分かりやすさのバランス
- 結論から述べる完結な文書構造
- 事実と意見の分離
- 実践！テクニカルライディング
- 文章を書く流れ
- うまく書けない場合
- めっちゃ書いちゃう場合
- セルフレビューのテクニック
- メルカリ・メルペイにおける技術文書を書く機会
- 伝わる技術文書の書き方
何故参加したか
- 技術ブログをアウトプットするペースを早くしたい ※現状隔月1本
- 相手に伝わる技術ブログを書きたい
参加して学んだこと
技術ブログ初心者の観点で、動画から参考になった部分を引用して、学びをまとめてみました。
伝わる技術文書の書き方
- 外部公開の分類
- A. 理解した技術のまとめ
- B. 新たな技術のまとめ
- C. 自分で考えた手法（技術）のまとめ
- D. プロセス（プラクティス）改善・導入
- E. 自分の考えを伝えたもの
- F. 書籍の紹介
技術ブログは、新たな技術のまとめや、自分で考えた手法（まとめ）だけをイメージしていました。理解した技術のまとめや、書籍の紹介などであれば、アウトプットしやすいですね。
今すぐテクニカルライディングが必要になったときの転ばない杖
- 対象読者と期待値のコントロール
- 読者は筆者が思った通りには、行動しない
- そもそも文章を書いたら読んでもらえるというのは書き手の勘違い
- 対象読者を指定する
技術ブログを書いたら読んでもらえるという書き手の勘違いを、正にやっていました。書く時間を決めることで、アウトプットするペースが早くなるか試してみます。
また、対象読者を指定すること（本当は誰に届けたいの？と振り返る鉄の意思）で、書きやすくなると感じました。
実践！テクニカルライディング
- うまく書けない場合
- うまく書けない項や節を飛ばす
- 書きたいところから書く
- 見直すと不要な場合もある
うまく書けないところは、そもそも不要な場合がある、という点に気付けていませんでした。書けないところは思い切って捨ててみました。
- セルフレビューのテクニック
- 耳で聞く
- OSの読み上げ機能を使う
- 耳で聞いて頭に入ってこない文章は、読んでも分かりづらい
セルフレビューで耳で聞くという観点はありませんでした。実際に耳で聞いてみると、文章が冗長な点に気付けますね。テキストの読み上げは、AWSのAmazon Polly（テキスト読み上げ機能）も使えますね。
まとめ
今回は、技術ブログ初心者の観点で、オンライン勉強会『伝わる技術文書を書く』に参加した内容をアウトプットしてみました。技術ブログをアウトプットするペースを早くするには、テーマや対象読者を絞り込んだ上で、理解した内容をまとめることが効果的だと感じました。
最後になりますが、いつも良質な情報を公開して頂けるmerpayさんに感謝です。m(_ _)m