はじめまして！バックエンドエンジニアの小林です。 好きな音楽ジャンルは、エレクトロ・スウィングです。 ジャンルとしては、ジャズやスウィングを基礎に、ハウスやEDMを混ぜた音楽になります。 おしゃれな曲や踊りたくなる曲など、聞いていて楽しくなる曲が多い印象です！ 気になった方は検索してみてください。

はじめに

エンジニアのリモートワークが一般化し、文章によるコミュニケーションの機会が増えています。 このような環境下で、文章の作成能力を向上させるためにテクニカルライティングについて学びました。 本記事では、テクニカルライティングの学習中に、今後気を付けたいと思った点をまとめます。

テクニカルライティングとは

テクニカルライティングとは、技術的な情報を明確かつ簡潔に伝えるための文章の作成技術です。 「製品の取扱説明書」や「技術者向けのマニュアル」の作成を専門とするテクニカルライターと呼ばれる職業も存在します。

テクニカルライティングを学ぶメリットには、次のようなものがあります。

[ 書き手側のメリット ]

• 読み手に伝えたい情報を正確に伝えることができる
• 文章を作成する負担・時間が減る

[ 読み手側のメリット ]

• 文章を読む負担・時間が減る
• 文章の誤解が減る

エンジニアがテクニカルライティングを学ぶメリット

エンジニアは、日常的に技術的な情報を共有し、他のエンジニアや関係者と協力する必要があります。 テクニカルライティングを学ぶことで、技術的内容を分かりやすく、正確に伝える能力が向上し、プロジェクトの成功に貢献します。

具体的なメリットは以下の通りです。

• GithubやSlack上でのテキストコミュニケーションが円滑になる
• 仕様書や設計書といったドキュメントの質が高まる
• 作業や進捗の報告が明確になる

学習した内容

テクニカルライティングで学んだ内容を次のようにまとめ、共有していきます。

• 読み手を意識する
• 統一感のある文章を書く
• 誤解をされない表現を使う

読み手を意識する

読み手は、書いてある文章の全てを読むわけではない

読み手は、目的や興味に応じて、文章の一部だけを読むことがあります。 例えば、音楽制作用のソフトウェアを扱うサイトがあり、ソフトウェアの操作方法や機能、歴史が書かれていたとします。 この場合、音楽の制作自体に興味のある人は、ソフトウェアの操作方法や機能の部分だけを読み、ソフトウェアの歴史の部分は読まないかもしれません。

「読み手が書いてある文章の全てを読むわけではない」ということを考えると、以下のような点に気を付ける必要があります。

• 文章中に何度も出てくる専門用語は、初めに説明する
• 「結果」や「主張」、「結論」といった重要な情報を含む文章から先に書き、理由や補足情報を後に書く
• 主語の省略や指示語の乱用を避ける

音楽制作用のソフトウェアを扱うサイトを再び例に取ります。 音楽の制作自体に興味のある人を、メインの読み手として想定する場合、以下のような工夫をサイトに行うと良いでしょう。

• ソフトウェアの簡単な説明を初めに書く
• ソフトウェアの操作方法や機能の部分をサイトの先頭に書き、歴史の部分を後尾に書く

読み手を不安にする文章を書かない

読んでいて不安になる文章とは、例えば次のような文章です。

このソフトウェアは、めちゃくちゃ性能が高いです。おそらく、内部でAIを使っているからでしょう。
私が使ってみた感じでは、使いやすかったです。

読むと、すぐにレベルの低い文章だと感じるかもしれません。この文章の問題点を、言語化すると次のような点が挙げられます。

• 「めちゃくちゃ」、「感じ」という軽薄な表現が使われている
• 「おそらく」という曖昧な表現が使われている
• 「性能が高い」、「使いやすい」とのみ書かれおり、客観的な情報や具体的な情報が書かれていない

読み手に安心感を与えるために、これらの問題点は避けましょう。 文章の問題点を解消すると、例えば、次のようになります。

このソフトウェアは、従来のものより、生成速度が20%向上しています。内部にはAI技術が組み込まれており、生成速度の向上に貢献しています。
実際に使用してみたところ、インターフェースが直感的であり、操作が容易でした。

統一感のある文章を書く

統一感のある文章を書くための技術として、次のようなものがあります。

口語体

「ですます調」と「である調」を混在させず、統一します。

それぞれ印象が異なるため、文章によって使い分けます。

• 「ですます調」には、 柔らかく丁寧な印象がある
• 「である調」には、力強く堅い印象がある

視点

関連のある文章は、能動態と受動態を使い分けて、視点を統一させます。 例えば、操作手順書の文章は、利用者の視点で記述します。

• 利用者が操作する内容は、能動態で記述します。 → 「購入」ボタンにマウスポインターを合わせ、クリックします。

• 利用者から見て自動で行われる内容は、受動態で記述します。 → ボタンを押すと、「商品確定」メッセージが表示されます。

同義語

同じ意味の言葉が複数ある場合、文章全体で一つに統一します。