はじめに

エンジニアにとって、仕様書などの技術的な文章を書くこと（テクニカルライティングとも言います）は避けて通れません。ただ私も20年来同僚としてエンジニアの方々と接してきた中で思うのですが、エンジニアの方の中には「文章を書く」ということに苦手意識がある方も一定数いると感じています。

でもこの「テクニカルライティング」というのは一種の「技能」です。ある一定の原理原則を理解して実践を繰り返すことで、必ず一定レベルで習得できるものだと著者は信じています。

もしこのテクニカルライティングの原理原則をまだ体系的に学習していない、または過去学習したが改めて再学習したいという方に、お勧めのコンテンツを見つけたのでご紹介します。

https://developers.google.com/tech-writing

Every engineer is also a writer.

という一文で始まるこのコンテンツは、Googleが公開しているテクニカルライティングの教育用資料です。
テクニカルライティングの基本原則を、とても簡潔な文章と事例でわかりやすく紹介しています。そして何より嬉しいのが分量がコンパクト！

英語なのですが、読みやすい簡潔な英語ですし、Google翻訳などで十分に理解できます。英語が苦手な方にも負担は少ないと思います。（実際私も英語は得意ではありませんが問題なく読むことができました。）
何より、読みやすさとは言語の壁以上にその書き方や構成であることを身を持って表現しており、日本のエンジニアリング業界でより広く読まれて欲しいコンテンツだと感じました。

ここではこのコンテンツとそこで示されている基本原則を簡単にご紹介します。

コンテンツの構成

元々このコンテンツは初学者から教育者や職業ライターまでを広く想定されているようで、講義資料も事前学習コンテンツと講義（実践演習）コンテンツに分かれています。
この事前学習コンテンツが最低限の要素がコンパクトにまとまっており、とても素晴らしいと感じたのでこちらを紹介します。
この事前学習コンテンツは2部構成（One＆Two）になっています。以下それぞれ骨子と概要をなぞってみたいと思います。

Technical Writing One

Technical Writing Oneは、より明確な技術文書の書き方を教えています。
https://developers.google.com/tech-writing/one

目次はこちらです。

それぞれ各項目毎に説明コンテンツがあります。

最後のSummary（要点）部分を抜粋します。

※以下の翻訳はGoogle翻訳をもとに著者が訳したものです。誤訳あれば訂正しますのでご指摘ください。

• 用語は文書内で一貫性をもたせる
• 曖昧な代名詞の利用は避ける
• 受動態は避け、能動態を優先する
• 強い動詞を選択する（※1）
• 曖昧な動詞よりも意味が限定される動詞を選ぶ
• 1文1メッセージ
• 長い文章はリスト形式に変換する
• 不要な言葉は排除する
• 順序が重要な場合は番号付きリストを使用し、順序が重要でない場合は箇条書きリストを使用する
• リストを使う場合は言葉の並列性を保つ
• 番号の付いたリストは命令語で始める
• リストと表を適切に使う
• 段落の骨子を示す良いリード文を作る
• 1段落1トピックに絞る
• 読み手の前提知識を定義する
• 読み手を意識して書く
• ドキュメントの最初にそのドキュメントの重要なポイントを明確に示す

※1：強い動詞とは？→意味が明確になる動詞。

https://developers.google.com/tech-writing/one/clear-sentences

総じて言えば以下の2点が重視されていると言えるでしょう。

• 読み手を定義し常に読み手目線におくこと
• 読み手が極力読み違いや誤解を避けるように簡潔でわかりやすい記述にすること

Technical Writing Two

テクニカルライティング2は、技術者がテクニカルコミュニケーションスキルを向上させるのに役立ちます。
https://developers.google.com/tech-writing/two

目次はこちらです。

1と同じくそれぞれ各項目毎に説明コンテンツがあります。

最後のSummary（要点）部分を抜粋します。

• スタイルガイド（テンプレート）を採用する
• 読み手がどう思うかを考える
• 書いた文書を（自分自身で）声に出して読んでみる
• 下書きを書いた後少し寝かせてまた読んでみる
• 優れたレビュワーを見つける
• ドキュメントのアウトラインを作るか、または自由に書いた後にそれを整理する
• ドキュメントの対象範囲と前提条件を最初に示す
• できるだけタスクベースの見出しにする
• 伝えたい内容に応じて、情報は適切なステップやかたまりに分解して示す
• イラストを作成する前に、説明書きを書いてみる
• 1つの図面内の情報量を制限する
• キャプションで要点を説明するか、画像に注意を惹くマークを追加して、画像または図の適切な箇所に読者の注意を向ける
• 理解しやすい簡潔なサンプルコードを作成する
• コードのコメントは短くして、簡潔さよりも明快さを優先する
• 自明なコードにコメントは書かない
• コメントは、コード内の直感的でない部分を明らかにすることに集中させる
• 例だけでなく、反例も提供する
• コードサンプルは複数の複雑さを想定したものを提供する
• 継続的に見直すことを実践する
• ユーザーによってそれぞれ異なる資料形態を提供する
• 読者がすでによく知っているものと比較する
• チュートリアルでは、複数の例を使用して伝えやすくする
• チュートリアルでは、読者がつまづきやすい点を指摘する

Technical Writing Oneは主に各文や文章における情報伝達の最適化にフォーカスしていているのに対して、Technical Writing Twoはそのドキュメント（コンテンツ）全体として目的達成最大化のための原理原則を示しています。特に技術文書の場合は、図やサンプルコードを利用することが有意義な場合が多いので、その利用の留意事項も記載されています。

まとめ

以上Google社が公開しているテクニカルライティングの原理原則を示したコンテンツを紹介しました。
個人的には何度なく「audience」という単語が出てきたのが印象的でした。
言語や用途は問わず、「読み手が求めているものを読み手がわかりやすいように書く」ことが、一番大切なことなのだと痛感しました。
全部のコンテンツを翻訳しながら読んでも1~2時間ほどで読めるかと思いますので、テクニカルライティング力を強化したいという方は是非一度目を通してみてください。

https://developers.google.com/tech-writing/overview

その他参考リンク

https://developers.google.com/tech-writing/resources
のページで紹介されています。興味のある方は是非。

Technical writing resources  |  Google Developers

This style guide provides a set of editorial guidelines for anyone writing developer documentation for Google-related projects.

Google社のより具体的なドキュメントスタイルガイドラインです。フォーマットも細かく定義されています。

Welcome - Microsoft Style Guide | Microsoft Docs

Welcome to the Microsoft Writing Style Guide, your guide to writing style and terminology for all communication—whether an app, a website, or a white paper. If you write about computer technology, this guide is for you.

同様にMicrosoft社のスタイルガイドラインです。