OpenWork Tech Blog

社員クチコミサービスを運営しているオープンワークエンジニアによるテックブログです。

テクニカルライティングで文章の書き方を体系的に学ぶ

たまたま早起きできて出社した日のオフィスの画像です

はじめに

こんにちは。最近電車で知らない駅に行って散歩するのにはまっている、オープンワーク株式会社の23卒Webアプリエンジニアの室永です。

皆さんは「テクニカルライティング」という手法を知っていますでしょうか?
ドキュメントの書き方についての手法で、エンジニアとして業務に携わる中で持っていると非常に役立つスキルです。
今回はテクニカルライティングについて紹介しようと思います。

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

概要

テクニカルライティングとは「技術的な内容を読み手に分かりやすく伝える手法」です。
テクニカルライティングの原理原則を利用すると文章の「書き方」が体系的に分かり、読み手の認知負荷を下げることができます。(認知負荷は「読み手が理解するのに使う脳のメモリ」と考えて頂いて問題ないです。)

なぜ重要なのか

分かりやすい文章であれば、読み手の認知負荷と読むのにかかる時間を減らすことができます。
また、エンジニアが書いた文章は通常多くの人が読みます。 テクニカルライティングの原理原則を用いて書いた文章を多くの人に読んでもらう場合、それだけ読んでもらう人々の認知負荷と読む時間を減らせます。

コードを書く際にも、将来的な読解コストを減らすためにクリーンかつリーダブルなコードを書くのと同じです。

ユースケース

エンジニアであればテクニカルライティングのユースケースとして以下などが挙げられます。

  • ドキュメントを書く
  • コードのコメントを書く
  • 仕様書や設計書やBacklogのチケットを書く
  • テストケースを書く
  • ミーティングなどの議事録を書く
  • Slackなどのチャットツールでやり取りする
  • テックブログを執筆する... など

このようにエンジニアはコードだけでなく、文章を書く機会が多いです。

頭の片隅に置いておくべきドキュメントの性質

ドキュメントには以下のような性質があり、読み手によって専門性や読む目的などが違います。
以下の4人を例に説明します。

  • エンジニアA:ベテラン社員でABテスト実装の経験がある
  • エンジニアB:中堅社員でABテスト実装の経験がない
  • エンジニアC:新卒社員でABテストのことを知らない
  • プランナー:エンジニアの技術的なことは分からない

読み手によって必要な情報は違う

「ABテストについてのドキュメント」があった場合、上記の4人が「読む目的」はそれぞれ異なるはずです。

  • エンジニアA:ABテストで社内特有のエラーが発生したので、トラブルシューティングだけ知りたい
  • エンジニアB:ABテストの実装方法が分からないので、実装手順を一通り知りたい
  • エンジニアC:ABテストについて何も知らないので、ABテストの概要から実装手順まですべて知りたい
  • プランナー:ABテストのログの種類を知りたい

読み手によってドキュメントから得たい情報は異なります。

読み手によって読む箇所は違う

読む目的から推察すると、上記の4人は以下を読めば「得たい情報」が得られることが分かります。

  • エンジニアA:トラブルシューティングの項目
  • エンジニアB:実装手順の項目
  • エンジニアC:一通りすべて
  • プランナー:ログの種類の項目

ドキュメントは必ずしもすべて読まれるわけではないです。
一部のみ読まれることが前提だからこそ、「得たい情報」を見つけやすくなるような見出しやアウトラインなどの文章構成が重要になります。

読み手によって専門性が異なる

上記の4人では専門性や習熟度が異なります。

  • エンジニアA:開発の技術知識についてかなり詳しい
  • エンジニアB:開発の技術知識について詳しい
  • エンジニアC:開発の技術知識についてあまり詳しくない
  • プランナー:開発の技術知識は知らない

エンジニア以外も読む項目に、エンジニア専門用語などが入っていないでしょうか?
補足を入れたり用語についてのURLを添付したりなど、読み手の視点に立って書くことが重要です。

テクニカルライティングのコツ

認知負荷の低い文章構造の作り方

階層構造を意識する

マークダウン記法を使っている方であれば、以下のような文章構成をしているのではないでしょうか。

  • 一つのファイルに一つの大きなテーマ
  • 一つの見出しに一つの小さな単位のテーマ
  • 一つの小見出しや一つの段落に一つのトピック

一つの文章構成には原則一つの関心事を書くと、まとまりの良い文章になると思います。単一責任の原則(一つのクラスには一つの責務のみを持たせる)と近い考えですね。
また、階層構造を意識することで「情報の探しやすさ」も向上します。(あちこちに情報が分散していると色々な箇所を読む必要があります。)

階層構造のドキュメントの例

階層構造の考え方は、ディレクトリ配置などの構成を考える際にも使えると思います。

アウトラインを作成する

長大なドキュメントでは目的の情報がどこにあるか分からないことがあります。
アウトラインとは目次のようなもので、予めどのような情報があるかを読み手に提示し、情報を探しやすくすることができます。

本記事でも目次を最初に提示しています。

目次

段落の単位を意識する

段落は一文の主題と数文の補足で構成されます。 冒頭にその段落での結論や伝えたい重要なことを書き、後の数文は理由や詳細、根拠などの補足情報を書きます。

あくまで、一つの段落の中に書くのは一つのトピックだけです。

認知負荷の低い文章の作り方

認知負荷の低い文章を作成するには、とにかく簡潔・短い・分かりやすい文章を書くことを意識することが重要だと思います。
コードでも簡潔で短く、分かりやすい方が保守も読解も工数が少なくなります。

結論や重要なことから書く

最初に結論や重要のことを提示すると、その後の補足情報が頭に入りやすくなります。

❌ 脆弱性やバグ修正のサポートが受けられなくなります。なので、PHPの定期的なバージョンアップは重要です。
✅ PHPの定期的なバージョンアップは重要です。なぜなら、脆弱性やバグ修正のサポートが受けられなくなるからです。

一文に一つのメッセージで書く

一文を短くし二つ以上のメッセージを詰め込まないようにすることで、認知負荷を下げることができます。

❌ SymfonyはPHPのWebアプリケーションフレームワークで、MVC(Model View Controller)モデルを採用しています。
✅ SymfonyはPHPのWebアプリケーションフレームワークです。MVC(Model View Controller)モデルを採用しています。

並列情報は箇条書きや番号付きリストで書く

並列情報は箇条書きや番号付きのリストで書くことで、視認性が向上します。

❌ PHP8.3ではクラス定数の型付けやクラス定数の文字列指定、#[\Override]のアトリビュートなどの新機能が追加されました。
✅ PHP8.3には以下の新機能が追加されました。
・クラス定数の型付け
・クラス定数の文字列指定
・#[\Override]のアトリビュート

ここでの並列情報というのは、同じ種類の情報(上記例文であればPHP8.3の新機能)です。

具体的に書く

抽象的な言い回しは理解が難しいです。
具体的に書いたり、例示をすることで認知負荷を下げられます。

❌ Rectorのバージョンを確認してください。
✅ composer.jsonのRectorのバージョンが1.2以上であることを確認してください。

特にエンジニア向けのドキュメントでは、実際のコード例、クエリ、コマンドなどは強力な具体例となると思います。

適切な箇所に句読点を打つ

文章の区切れに適切に句読点を打つことで、文章の区切りが明確になります。

❌ Symfony6.0にバージョンアップするとSessionInterfaceのDIができなくなります。
✅ Symfony6.0にバージョンアップすると、SessionInterfaceのDIができなくなります。

認知負荷の高い言い回しをしない

コードを書くときに、複雑に三項演算子を乱用したり、変数のスコープが広かったり、二重否定したりすると可読性が下がります。
文章も同様で、複雑な言い回しをしたり、修飾・被修飾のスコープが広かったり、二重否定を使ったりすると認知負荷が高まります。

❌ flakyでないテストは対応しないでください。
✅ flakyなテストを対応してださい。

図表を活用する

図や表は文章を読むよりも圧倒的に認知負荷が低いです。
書いている文章を表にまとめることはできないか?文章のみだとイメージが湧きにくいのではないか?など考えてみるのも良いと思います。

❌ 今回のABテストの仕様では、Aパターンではデフォルトと同じ、Bパターンではトップページに求人を表示します。
✅ 今回のABテストの仕様は以下です。
パターン 仕様
Aパターン デフォルトと同じ
Bパターン トップページに求人を表示する

読み手の立場で書く

読み手は誰か?その読み手はどのような情報を得るために読むのか?読み手はどこを読むのか?を意識しましょう。

最後に

いかがでしたでしょうか?テクニカルライティングを体系的に学び、良い文章を書けるようになるとエンジニアとして一段階スキルアップできるはずです。
また、テクニカルライティングの原理原則とコードの原則で似通っているものもあったのではないかと思います。
分かりやすく認知負荷の低い文章を書くスキルは良いコードを書くスキルに通じるでしょう。

今回私が執筆した内容は、Webアプリエンジニアで週次開催しているLightning Talkの内容でした!
オープンワークではこのように社内で情報発信できる機会もあるので、この記事を読んで少しでも興味を持った方はぜひ採用サイトを覗いていただけると嬉しいです!

www.openwork.co.jp