はじめに
テクニカルライティングは、開発者にとってコーディングと同じくらい重要だと思っています。
またこれから先、さらにその重要度は増してくるはずです。
そして技術的なドキュメントを書く際、最も重要な要素の一つは「ワンセンテンス・ワンメッセージ」だといえるでしょう。
この原則を守ることで、読み手にとって理解しやすい文章を提供できます。
本記事では、テクニカルライティングの重要性と「ワンセンテンス・ワンメッセージ」の原則について解説します。
そもそも
なぜこれから先、テクニカルライティングがより重要になってくるのでしょうか？
そもそもこれまでも開発者は、多くのドキュメントを作成する必要がありました。
以下は、その一例です。
- 開発チケット
- 仕様書
- 手順書
- 顧客向けマニュアル
- 問い合わせ対応
そして生成AIが開発サイクルに組み込まれることが一般化する中で、「プロンプトエンジニアリング」と呼ばれる新たなスキルが求められています。
このプロンプトエンジニアリングは、AIに対して正確な指示を与えるためのスキルであり、テクニカルライティングと密接に関連しています。
極端なことを言えば、これまで開発者一人だけで完結するのであればドキュメントの重要性は低かったかもしれません。
しかし仮に開発者が一人だったとしても、開発サイクルにおいて「一切AIを用いない」という時代はおそらくもう戻ってきません。
要件定義、実際のコーディング、技術的な調査、、、その場面は色々でしょうが、必ずAIをうまく扱う必要性が出てきます。
そしてそのAIに対して正確な指示を与えるためには、明確かつ簡潔な表現能力が求められます。
これこそが、テクニカルライティングがこれから先、さらに重要になると考える理由です。
ワンセンテンス・ワンメッセージの原則
では実際にそのテクニカルライティングの中でも、特に重要で基礎的な原則である「ワンセンテンス・ワンメッセージ」について解説していきます。
「一文一義」とも呼ばれますが、読んで字のごとく、1つの文(センテンス)に1つの意味(メッセージ)だけを込めるという原則です。
これにより、文章が明確になり、読み手にとって理解しやすくなります。
Device and Conquer
「Divide and Conquer(分割統治法)」という言葉がありますが、これは「大きな問題を小さな問題に分割して解決する」という考え方です。
この考え方は、ワンセンテンス・ワンメッセージを達成するためにも非常に役立ちます。
「Divide and Conquer」を意識することで、１つの長文を複数の短文に分割し、自分の言いたいことを正確に伝えられるようになります。
意識すること
2025年5月現時点で自分が実践しているテクニックや考え方を紹介します。
また何か新しく意識する観点を見つけたら、随時更新していきます。
文章の主目的を明確にする
まずなによりも、文章の主目的を明確にしましょう。
そのためには、「自分が知っていること」をすべてダラダラと書くのではなく、
「自分が相手に伝えたいこと」を明確にする必要があります。
ドキュメントを作成する際、以下のような質問を自分に投げかけてみると良いでしょう。
- そもそも文章全体は読み手に何を伝えたいのか？
- この文章を読んだ後、読み手は何を理解しているべきか？
- この文章を読んだ後、読み手はどのようなアクションを取るべきか？
- その中で、特にこのセンテンスは何を伝えたいのか？
- 文章全体の中で、このセンテンスはどのような役割を果たすべきか？
改行と分割
文章を短くするためにも、改行や文の分割を意識しましょう。
(以下に例を示していますが、内容はかなり適当です)
具体例1: AWSに関する説明
Before:
AWSは非常に多くのクラウドサービスを提供しているため、企業は必要に応じたサービスを柔軟に選択できるが、いくつかのサービスは設定が非常に複雑であるため、特に初心者にとっては理解することが難しく、導入に時間を要する場合もある。
After:
AWSは非常に多くのクラウドサービスを提供している。
これにより、企業は必要に応じてサービスを柔軟に選択できる。ただし、その中には設定が非常に複雑なサービスがある。
そのため、特に初心者には理解が難しく、導入に時間を要する場合もある。
具体例2: TypeScriptに関する説明
Before:
TypeScriptはJavaScriptに対して型付けの概念を導入するが、これによりコードの予測可能性と安定性が向上する点が開発者にとって非常に魅力的であるにもかかわらず、JavaScriptについての知識が前提となるため、TypeScriptの学習曲線は急峻であるといえ、新しい開発者にとっては難しい場合が多い。
After:
TypeScriptはJavaScriptに対して型付けの概念を導入する。
この型付けにより、コードの予測可能性と安定性が向上する。
これは開発者にとって非常に魅力的である。しかしその一方で、JavaScriptについての知識が前提となっている。
このため、TypeScriptの学習曲線は急峻であるといえる。よって、新しい開発者にとってTypeScriptの習得は難しい場合が多い。
読み飛ばしを許容する
読み飛ばしを許容することは重要です。
読み手に事前情報や背景知識がある場合には、読み飛ばしを許容することで、むしろ重要な情報に集中させることができます。
このためにも先述のように、文章を短く分割することが重要です。
(もし一文が長すぎる場合は、部分的な読み飛ばしができないため、結果として読み手はその文章全体を読み飛ばすことになります)
読点の削減
読点を減らすことを意識することで、結果として一文一文が簡潔になります。
あくまで感覚値ですが、一文における読点の数は1～2個までに抑えることを意識しましょう。
なにも意識せずに読点を打った際には、まず一度そこで文章を区切ることができないか考える癖をつけるといいです。
では、逆に読点を使うべき場合はどのような時でしょうか？
一つの目安として、読点は「紛らわしい場合」にのみ使うべきです。
具体例: 中学時代のあだ名
Before:
私は中学時代にー君と呼ばれていました。
After:
私は中学時代、にー君と呼ばれていました。
箇条書きやリストの活用
文章が長くなる場合は、箇条書きやリストを活用することで、情報を整理しやすくなります。
可能であれば、箇条書きやリストを使うことを前提に文章全体を構成してもいいかもしれません。
具体例: アプリケーションの機能説明
Before:
ユーザー登録、ログイン、プロフィール編集、メッセージ送信といった機能を持つアプリケーションを開発する予定です。
After:
以下のような機能を持つアプリケーションを開発する予定です。
- ユーザー登録
- ログイン
- プロフィール編集
- メッセージ送信
主語と述語の整理
主語と述語を明確にし、誰が何をするのかをはっきりさせましょう。
具体例: プロジェクトの進捗報告
Before:
現在、開発チームとテストチームによるプロジェクトの進捗は思わしくなく、新しい機能の実装に取り組んでいる一方で、いくつかのバグを報告しており、緊急度が高いため、すぐに修正する必要があります。
After:
現在、プロジェクトの進捗は思わしくないです。
開発チームは、新しい機能の実装に取り組んでいます。
その一方でテストチームは、いくつかのバグを報告しています。
これらのバグは緊急度が高いため、開発者はすぐに修正する必要があります。
おわりに
「ワンセンテンス・ワンメッセージ」の効果を理解できたでしょうか？
もしそうだと大変うれしく思います。