短いメッセージを書くことはできても、まとまった文章を書くのに苦労している人は多いのではないでしょうか。
この記事では、まとまった文章を作るときの技術を学ぶことができる記事や学習コンテンツを紹介します。新人エンジニア向けです。
文章の「型」を学ぶ
まとまった文章を書くには、「型」が必要です。頻繁に使うものは、「型」を覚えてしまいしましょう。
バグレポートの書き方を学ぶ
エンジニアとして書く文章の代表例が、バグレポートです。
バグレポートでありがちな失敗として「何が問題だと思っているのか」が伝わらないというものがあります。
これを防ぐために、「期待する結果」「実際の結果」「再現手順」の3つを必ず書くようにしましょう。
質問の書き方を学ぶ
エンジニアが扱う技術は、最初はわからないことだらけです。
それを解決するために、質問の文章を作成する技術が必要となります。
概ね下記の4つの情報があれば、良い質問だと言えるでしょう。
- 何のためにやっているのか
- 何がわからないと思っているのか
- 自分で何をどこまで調べたのか
- エラーメッセージなどを貼り付ける
議事録の書き方を学ぶ
議事録の書き方を解説したページです。ポイントとして列挙されているうち、下記の2つは特に大事です。
- 「決定事項」と「ToDo」は全て明示する
- ToDoには「担当者」と「期限」を設定する
ただし、ポイント中の「役職名で表示」などは、所属する企業によっては不要かと思います。
個人的には、社内での仕事で、特に役職名を意識したことはありませんので・・・。
また、Wordにこだわることもないと思います。
具体的な文章に対して、読みやすい議事録の書き方を解説しているページもあります。
動画で学ぶ
LINE株式会社 テクニカルライターの矢崎 誠さんによる動画です。
1つあたり30分程度で、具体的な実例をもとに学ぶことができます。
これだけ気を付けて書いてもらえるとみんな幸せになるポイント2つだけ
- 何を指しているのかを明確にするために、文章中の「名前」を大事にする
- 読者との距離を近づけるために、タイトルと概要に時間をかける
説明の順番も大事な情報
- 文章は「思いついた順」に書いてよい
- ただし「並べる順番」に気を配る
手を動かして学ぶ
手を動かして学べるような、練習問題が用意されているページです。
読みやすい文章の書き方を学ぶ
書籍『数学文章作法』の著者である結城浩先生が公開されているページです。
- 文を短くしましょう
- 適切な単語を選びましょう
- パラレリズムを使いましょう
- 自然な順序で書きましょう
- 語順を変えてみましょう
- 重要点は2回書きましょう
- よい比喩を使いましょう
- まずはどんどん書きましょう
- 接続詞をうまく使いましょう
- ストレートに書きましょう
記述パターンを学ぶ
以下は、過去に私が書いた記事です。
文章の型(記述パターン)を覚えると、文章をうまく作成することができます。
文章校正を学ぶ
漢字とひらがなの使い分けを学ぶ
山之内総合研究所による「漢字書きが適当な語」と「ひらがな書きが適当な語」のまとめです。
すべて覚えるのは難しいですが、ある程度は暗記できるのではないかと思います。
機械に文章校正させる方法を学ぶ
エンジニアたるもの、機械に自動的なチェックをさせましょう。
個人的には、textlintを使った方法をおすすめします。