はじめに
技術ブログの記事やドキュメントを書くなど、文章でアウトプットする機会は多いが、自分の書いた記事が伝わりやすい文章になっているか、いまいち自信がないかたは意外と多いのではないでしょうか。
読者や目的に合わせて技術をわかりやすく伝える手法を、テクニカルライティングというそうです。アウトプットするときに、より伝わりやすい文章を書くために、テクニカルライティングについて調べてみました。
この記事では、調べた際に参考になった記事をいくつか紹介しようと思います。伝えやすい文章を書きたい、テクニカルライティングについて知りたい、と思っている人の参考になれば幸いです。
良かった記事
テクニカルライティングの基本
- サイボウズ新入社員向け研修資料
- 伝える情報の整理やアウトライン作りなど、わかりやすかった
- 書くときの心構え、チェックシートのスライドは、意識できればすぐ改善につながりそうでした
- 何かしら文章を書く際には手元で開いておきたい
- 動画もあった
LINE社内で大評判のテクニカルライティング講座で説明した内容をあらためてブログにまとめてみた
-
LINE Engineering のブログ記事
-
バッドパターンから、どうしたら伝わりやすい文章になるか、改善していく過程が書かれていて、わかりやすいかった
-
とりあえず、わかりやすい文章を書くためには、文は短くしようという気持ちになった
- （ので、し、などの接続詞が出てきたら注意）
-
文章を書く際のチェック項目引用。重要そうなので常々意識したい
・主語と述語を明らかにする
・文を短くする（ので、し、を敵視する）
・文を短くする（箇条書き、表を使って情報を分断する）
・語順に気を配る
・読み方を工夫しなくてもわかる文章を書く
・前提知識が必要な場合は注意する -
「文章を工夫して書こうとしてる時点で、読者に伝わらない可能性が非常に高くなってる」と書かれていたのは、なるほどなあと思いました。（工夫しないとわからないということは、元がわかりずらいから、改善の余地がある）
LINE社内テクニカルライティング講座第2弾！1文では説明が終わらない文章を書くコツ
-
LINE Engineering のブログ記事
-
タイトルと概要を使って読む価値があるかどうか読者に判断してもらえるようにする、の重要そう
タイトルは「書き手が文章で伝えたいことに、読み手を近づけるために、問題点や結論を言って、話題を限定するための情報」
「その文章の話題を限定できるタイトル」をつけられない場合があります。
そのようなときに2つ目の部品である「概要」で、話題をさらに限定しましょう -
ちなみに、LINE社にはテクニカルライティングの専門のチームがあるそうです。すごい
開発ドキュメントの書き方。意識したい9つのこと【技術編】
-
テクニカルライターをされてるかたの開発ドキュメントのかき方、意識したいことについて書かれた記事
-
ここでも文章を短くするとあったので、やはり文章を短くするのは重要そう
-
ブログ全体で長文じゃなかったのでわかりやすくて、読みやすかった
-
9つ意識したいこと引用。
- 一文を短く切る
- 結論を先に述べる
- 指示語を使わない
- 主語を明確にする、述語との距離を近づける
- ひらく・閉じるを統一する
- 再現条件を示す
- 前提を揃える
- 見出しや箇条書き、表などを適切に用いる
- 読者に伝わる用語を使う
Google社のテクニカルライティングの基礎教育資料がとても良かったので紹介したい
-
Google社が公開しているテクニカルライティングの教育用資料の紹介記事
-
元々の資料サイトはこちら（コースは3部構成のよう）
-
最初のページに、
Every engineer is also a writer.と書いてあって、かっこいい -
学習すること引用
略語や頭字語などの用語を一貫して使用します。
あいまいな代名詞を認識します。
能動態と受動態を区別します。
受動態文を能動態に変換します。
能動態が受動態より優れている3つの方法を特定します。
文をより明確で魅力的なものにするために、少なくとも3つの戦略を立てます。
文を短くするために少なくとも4つの戦略を開発します。
箇条書きと番号付きリストの違いを理解します。
役立つリストを作成します。
段落の効果的なリードセンテンスを作成します。
各段落を1つのトピックに集中させます。
各ドキュメントの冒頭に重要なポイントを記載します。
ターゲットオーディエンスを特定します。
ターゲットオーディエンスがすでに知っていることと、ターゲットオーディエンスが学ぶ必要があることを決定します。
知識の呪いを理解する。
イディオムを特定して修正します。
ドキュメントの範囲（目標）と対象者を記述します。
長いトピックを適切なセクションに分割します。
カンマ、括弧、コロン、全角ダッシュ、およびセミコロンを適切に使用してください。
Markdownで初心者の能力を開発します。 -
英語がわかる人は良さそう
おわりに
いくつか記事を読んでみましたが、どの記事も参考になりました。共通してた内容が多くあり、重要そうなので実践していきたい。
- 文章を短くする
- 読者イメージする
- 重要なことから書く（結論から述べる）
- 主語と述語を近づける、主語を明確にする
今回読んでみた記事は、基本的なことが多かったと思うので、少しずつ慣れてきたらもっと調べてみたいと思います。（テクニカルライティング奥が深そう）
Every engineer is also a writer !!!!!!
Discussion