はじめまして！バックエンドエンジニアの小林です。
好きな音楽ジャンルは、エレクトロ・スウィングです。
ジャンルとしては、ジャズやスウィングを基礎に、ハウスやEDMを混ぜた音楽になります。
おしゃれな曲や踊りたくなる曲など、聞いていて楽しくなる曲が多い印象です！
気になった方は検索してみてください。
はじめに
エンジニアのリモートワークが一般化し、文章によるコミュニケーションの機会が増えています。
このような環境下で、文章の作成能力を向上させるためにテクニカルライティングについて学びました。
本記事では、テクニカルライティングの学習中に、今後気を付けたいと思った点をまとめます。
テクニカルライティングとは
テクニカルライティングとは、技術的な情報を明確かつ簡潔に伝えるための文章の作成技術です。
「製品の取扱説明書」や「技術者向けのマニュアル」の作成を専門とするテクニカルライターと呼ばれる職業も存在します。
テクニカルライティングを学ぶメリットには、次のようなものがあります。
[ 書き手側のメリット ]
- 読み手に伝えたい情報を正確に伝えることができる
- 文章を作成する負担・時間が減る
[ 読み手側のメリット ]
- 文章を読む負担・時間が減る
- 文章の誤解が減る
エンジニアがテクニカルライティングを学ぶメリット
エンジニアは、日常的に技術的な情報を共有し、他のエンジニアや関係者と協力する必要があります。
テクニカルライティングを学ぶことで、技術的内容を分かりやすく、正確に伝える能力が向上し、プロジェクトの成功に貢献します。
具体的なメリットは以下の通りです。
- GithubやSlack上でのテキストコミュニケーションが円滑になる
- 仕様書や設計書といったドキュメントの質が高まる
- 作業や進捗の報告が明確になる
学習した内容
テクニカルライティングで学んだ内容を次のようにまとめ、共有していきます。
- 読み手を意識する
- 統一感のある文章を書く
- 誤解をされない表現を使う
読み手を意識する
読み手は、書いてある文章の全てを読むわけではない
読み手は、目的や興味に応じて、文章の一部だけを読むことがあります。
例えば、音楽制作用のソフトウェアを扱うサイトがあり、ソフトウェアの操作方法や機能、歴史が書かれていたとします。
この場合、音楽の制作自体に興味のある人は、ソフトウェアの操作方法や機能の部分だけを読み、ソフトウェアの歴史の部分は読まないかもしれません。
「読み手が書いてある文章の全てを読むわけではない」ということを考えると、以下のような点に気を付ける必要があります。
- 文章中に何度も出てくる専門用語は、初めに説明する
- 「結果」や「主張」、「結論」といった重要な情報を含む文章から先に書き、理由や補足情報を後に書く
- 主語の省略や指示語の乱用を避ける
音楽制作用のソフトウェアを扱うサイトを再び例に取ります。
音楽の制作自体に興味のある人を、メインの読み手として想定する場合、以下のような工夫をサイトに行うと良いでしょう。
- ソフトウェアの簡単な説明を初めに書く
- ソフトウェアの操作方法や機能の部分をサイトの先頭に書き、歴史の部分を後尾に書く
読み手を不安にする文章を書かない
読んでいて不安になる文章とは、例えば次のような文章です。
このソフトウェアは、めちゃくちゃ性能が高いです。おそらく、内部でAIを使っているからでしょう。 私が使ってみた感じでは、使いやすかったです。 |
読むと、すぐにレベルの低い文章だと感じるかもしれません。この文章の問題点を、言語化すると次のような点が挙げられます。
- 「めちゃくちゃ」、「感じ」という軽薄な表現が使われている
- 「おそらく」という曖昧な表現が使われている
- 「性能が高い」、「使いやすい」とのみ書かれおり、客観的な情報や具体的な情報が書かれていない
読み手に安心感を与えるために、これらの問題点は避けましょう。
文章の問題点を解消すると、例えば、次のようになります。
このソフトウェアは、従来のものより、生成速度が20%向上しています。内部にはAI技術が組み込まれており、生成速度の向上に貢献しています。 実際に使用してみたところ、インターフェースが直感的であり、操作が容易でした。 |
統一感のある文章を書く
統一感のある文章を書くための技術として、次のようなものがあります。
口語体
「ですます調」と「である調」を混在させず、統一します。
それぞれ印象が異なるため、文章によって使い分けます。
- 「ですます調」には、 柔らかく丁寧な印象がある
- 「である調」には、力強く堅い印象がある
視点
関連のある文章は、能動態と受動態を使い分けて、視点を統一させます。
例えば、操作手順書の文章は、利用者の視点で記述します。
- 利用者が操作する内容は、能動態で記述します。
→ 「購入」ボタンにマウスポインターを合わせ、クリックします。 -
利用者から見て自動で行われる内容は、受動態で記述します。
→ ボタンを押すと、「商品確定」メッセージが表示されます。
同義語
同じ意味の言葉が複数ある場合、文章全体で一つに統一します。
- 「ユーザー」と「利用者」
- 「アプリ」と「アプリケーション」
誤解をされない表現を使う
誤解をされない表現は、次のようなものがあります。
一文一義
1つの文では、1つの内容のみ扱います。
「〜し」「〜ので」「〜けれど」などの接続助詞を文中に使っている場合、文を分割することを検討します。
箇条書きや連番を使うことで、文を分割することもできます。
- 商品を追加し、「レジ」ボタンをクリックし、「確定」ボタンをクリックすることで、商品が購入できます。
↓ - 以下の手順を実行することで、商品が購入できます。
1.商品を追加
2.「レジ」ボタンのクリック
3.「確定」ボタンのクリック
主語と述語
文の主語と述語を正しく対応させます。
文が長くなり、主語と述語が離れてしまうと、主語と述語の対応が分かりづらくなります。
- EDMは、主にクラブやフェスティバル、ラジオなどで人気の高い音楽ジャンルであり、今日では多くのアーティストが、既存の音楽ジャンルと融合させ、新しい音楽の可能性を広げている。
↓ - EDMは、主にクラブやフェスティバル、ラジオなどで人気の高い音楽ジャンルである。
今日では多くのアーティストが、既存の音楽ジャンルとEDMを融合させ、新しい音楽の可能性を広げている。
否定
否定の表現は、なるべく避け、肯定の表現を使います。
- 安全でない → 危険である
終わりに
テクニカルライティングの学習中に気を付けたいと思った点をまとめました。
テクニカルライティングを学ぶ前、私は物事を明確に伝えるのが苦手でした。文章が冗長になったり、重要な情報が抜けていることが多く、チームメンバーからのフィードバックも良くありませんでした。
しかし、テクニカルライティングを学んだ結果、情報を整理し、簡潔に伝える方法を身につけれたかなと思います。
まだ、実践し始めたばかりで「文章を作成する負担や時間が減る」といったメリットは実感できていませんが、今後も学んだことを意識しながら文章を書いていきたいと思います。
最後までお読みいただきありがとうございました！
