技術文書を書く方に送る、書籍「技術者のためのテクニカルライティング入門講座」
開発関連技術
テクニカルライティング
こんにちは、積読の消化が追いついてねぇ…とぼやいてる、よしです。
今回は、読んだ書籍を紹介したい気持ちになりまして、紹介記事に挑戦してみました。
はじめに#
紹介したい本#
「技術者のためのテクニカルライティング入門講座」という書籍です。
以下、翔泳社のサイトより引用.
日本では、「文書は論理的かつ簡潔に記述する」という、当たり前のテクニックを学ぶ機会があまりありません。
そこで本書では、忙しい技術者の方でも「テクニカルライティング」を通じて、相手に伝わる技術文書を効率よく書けるようになるテクニックを多数紹介していきます。
ユーザーマニュアルや障害報告書、提案書といった実務直結の文例を多数掲載しているので、すぐに業務に役立てることが可能です。
新人～中堅の技術者の方だけでなく、管理職の方も添削指導のお手本としてご利用いただける内容です。
そもそも「論理的」とはどういうことなのか？というところから始まり。
ロジカルライティングとは？ テクニカルライティングとは？
と基礎的な考え方を提示しつつ、具体的なテクニックを紹介。
さらにそれらのテクニックを組み合わせて、実際の技術文書をどう作っていくのかという実例まで記載されている書籍です。
書籍が発売されたのは2018年11月19日。
当記事の執筆時点からは約5年前になりますが、今でも十分通用する内容になっていると個人的に思いました。
紹介したいと思った背景#
（私事なので興味ない方はすっ飛ばしてもらって大丈夫です）
自分は今の会社に来てから「ドキュメント力が高い」と評価されることが増えました。
（図的なドキュメントは大して描いたことがないので、多くは文章能力のことを指して言われていたのだと思っています）
それまでは特に自分の長所のような自覚は全くなく。
評価されるようになったことで、これって出来てる方なんだーとやっと自覚するようになり。
「技術記事書いてるから自然と伸びたのかな？」
「Textlint を活用したり、ネットで聞き齧ったテクニックを取り入れたりしてたおかげ？」
と思いつつ、そういえばちゃんと基礎からライティング技術を学んだことなかったなぁと。
自分の長所だというなら、ちゃんと基礎から学んでより磨いていきたい。
学んだことを周囲の人にも伝えられるようになれたら、より良いだろうなと思ったこともあり。
それで書籍を読んでみようとまず手に取ったのが、今回の書籍でした。
読んでいて、技術文書の書き方悩んでる人、みんなこの本読んだらいいんじゃないか？と思ったのがきっかけです。
基礎の基から具体的なテクニック〜実践まで記載されていたので、紹介されているテクニックを取り入れるだけでも十分役に立つと思ったのです。
書籍の内容の紹介#
書籍の目次はこのようになっています。
- 第1章：ロジカルライティング × テクニカルライティング活用の基礎知識
- 第2章：わかりやすく、簡潔な文章を書くテクニック
- 第3章：読み手に伝わる文章を書くテクニック
- 第4章：読みやすさを高める文書フォーマット〜表現・表記のルール〜
- 第5章：実践編 ユーザーマニュアル・取扱説明書
- 第6章：実践編 提案書
- 第7章：実践編 障害報告書
- 第8章：実践編 社外メール文
冒頭でも触れた通り、基礎知識〜テクニック・ルール〜実践といった流れですね。
テクニックの章だけでも、それぞれ before・after 例が提示されているためわかりやすいです。
今回は1〜3章の内容について少し紹介してみます。
第1章 - ロジカルライティング × テクニカルライティング活用の基礎知識#
第1章の目次.
- 1.1：技術者の書く文章がわかりにくい3つの理由
- 1.2：そもそも「論理的」とはどのようなことか
- 1.3：思考を効果的にアウトプットするための「ロジカルライティング」
- 1.4：「読み手」は目の前にいる人だけ？
- 1.5：「目的」ありき。読んだ人の行動を想定する
- 1.6：書き出す前にロジックを組み立てることが何より重要
- 1.7：情報をわかりやすく伝えるための「テクニカルライティング」
まずはよくあるアンチパターンに触れつつ、大事な基本的考え方から記載されています。
これまで論理的、ロジカルライティング、テクニカルライティングという言葉はよく聞いていたものの。
その意味がちゃんと説明できるか？と言われると自信がなかったため、改めて認識する良い機会になりました。
書籍の説明文をざっくり引用すると、こんな感じ。
- 論理的：わかりやすく伝わり、読み手の次の行動につながるほど筋道が通っていること
- ロジカルシンキング：論理的で筋道の通った思考方法や説明の仕方
- ロジカルライティング：ロジカルシンキングを活用して文書作成する技術
- テクニカルライティング：技術的な情報を利用者にわかりやすく伝えるための文書技術
技術文書は、ロジカルライティングとテクニカルライティングを組み合わせて記述していくものと考えると良さそうですね。
まずは読み手を洗い出し、文書の目的と読み手に期待する次の行動を明確にする。
というのが、技術文書を書く上ではとても大事である旨記載されています。
ここがブレてしまうと曖昧な内容になってしまい、結局何が言いたいのかよくわからないものになってしまいがち。
要らぬ不安や混乱を招いてしまうこともある…とあり、心当たりある気がしました😇
その次に、いきなり文書を書き始める前に、情報を整理してロジックツリーを組み立てようとありました。
主題を元に整理した情報を階層のツリーにして、全体像のイメージを作成。そこからポイントを設定。
各ポイントには、ポイントを裏付けるような内容を書いていく、といった感じ。
技術記事だったら、最初にタイトルを決めて見出し構成を決めた後に、それぞれの見出しの内容を書いていくといった具合ですね。
第2章 - わかりやすく、簡潔な文章を書くテクニック#
第2章の目次.
- 2.1：1文1義で書く
- 2.2：文を長くしない。「〜（だ）が」、「〜ので」で文をつながない
- 2.3：一文を短く。50字以内で収めるように
- 2.4：5W2H を盛り込み、曖昧な文章にしない
- 2.5：メールの件名、文書のタイトルから目的が伝わるように書く
- 2.6：「話し言葉」と「書き言葉」を使い分ける
- 2.7：接続詞の使用は最小限に抑えて、効果的に使う
- 2.8：長くなりがちな文章を簡潔に仕上げるコツ
この章では、冗長的で曖昧な文章とならないようにするテクニックが紹介されています。
なんとなく意識できていたものもあれば、ちょっと自信がないものもありましたね😓
特に「〜（だ）が」、「〜ので」って割と使いがちと言いますか。
これが良くない理由としては、以下のようなことが挙げられていました。
- 複数の内容が1文に盛り込まれてしまい、1文1義にならない
- 文の中で最も伝えたいことが、文の最後にきてしまう
このせいで、内容が読み手に伝わりにくくなってしまう、というものです。
とはいえ、文章を書きながら注意するのは難しいこともあり。
書き上げた後の見直しの段階で文を区切ったり、順番を変えたりすると良いとのことでした。
個人的には、完全に使わないようにするというよりは、多用しないように気をつけようかなと思っています。
（当記事でもいくつかは使用していたりします🙄）
それと「話し言葉」と「書き言葉」を使い分けるというのは、場合にもよりそうかなと。
書き言葉の方が冗長な表現を省いており簡潔に伝わりやすい。
礼節や説得力を高めるためにもビジネス上はこちらを使った方が良い、というのは確かにそうだと思いつつ。
技術記事であれば、きっちり書き言葉でなくても良いかなとは思いました。
きっちりだとなんだかお固い印象を与えてしまいそうな気がしまして。
ちなみに最初に目次を見た時、目次にあるタイトルだけでも何が言いたいのか率直に伝わってきました。
2.5のテクニックがまさに実施されているんだなぁとちょっと感激したものです。
第3章 - 読み手に伝わる文章を書くテクニック#
第3章の目次.
- 3.1：最も重要な内容を先に書く
- 3.2：形容詞や名詞句でなく、動詞でズバリと書く
- 3.3：否定表現に気をつける
- 3.4：受動態と能動態を使い分ける
- 3.5：具体的に情報を盛り込んで書く
- 3.6：「など」を多用しない
- 3.7：レビューを受けて、わかりやすさを高める
- 3.8：最後の文でしっかりと締めくくる
この章では、より読み手に内容や目的が伝わるような文章を書くためのテクニックが紹介されています。
うーん、こちらも出来ているものもあれば、自信ないものがある…。
「〜しないと、〜ない」や「〜しないとは限らない」のような二重否定を使っていませんか？
特に後者の方は「必ずしもそうなるわけではなくて、状況による」と曖昧な表現をしたくなった時に使いたくなったりしますよね。
こういった二重否定は、パッと内容が分かりにくくなってしまって、結局何が言いたいのかストレートに伝わらない問題を抱えているとのこと。
読み手に書き手の意図を考えさせてしまう、迷わせてしまうので避けましょうと。
「など」を多用しない、というのは特に自信がないやつですね。
「ここに挙げたのは一例で他にもあるよ」という時につい使いがち。
良くない理由として、これも文章を曖昧にしてしまう要因になるためでした。
対処法としては、「など」を削除してしまう。
もしくは「〜などの工具」のように、「など」の後に例示をまとめるようなものを加えること。
こうすることで「など」が何を示すのかを明確にして曖昧とならないようにすると良いそうです。
読んでみてどうだった？#
冒頭に述べた通り、この書籍の発売日が5年前であるため、古い情報もあるかな？と最初は思っていました。
実際に読んでみると、全部がとまでは言いませんが、十分今でも通用する考え方やテクニックが記載されている印象を受けましたね。
基礎知識の地盤固めにとても良く、読んで良かったなと。
テクニックがしっかり言語化されているので、これを自分の中で落とし込みつつ。
周りのメンバーにも伝えていけると良いドキュメントを作成する環境にしていけそうです。
だからこそ紹介したいと思ったというのもあります。
テクニカルライティングとシステム開発は似てる？#
それと読んでいてすごく思ったのは、テクニカルライティングで技術文書を作成するフローやテクニックって、システムを作る時に考えることと似ているなぁと。
フローで言うとこんな感じ。
| 技術文書 | システム |
|---|---|
| 情報収集〜整理 | 要件定義 |
| ロジックツリー作成 | 設計 |
| 執筆 | 実装 |
| レビュー | テスト |
プログラミングにおいても可読性って大事ですよね。
可読性向上のためのテクニックが多く存在するわけで。
それらの基本的な考え方って、分かりやすい技術文書を書くテクニックと同じなんじゃないかなーと思ったのです。
じゃあ、
優れた技術文書を書ける人 = 優れたシステムを作れる人
なのか…？
そこはどうなんだろうなぁと。
実装は得意でもドキュメント書くの苦手だと言う人もいるので、一概にそういうわけではなさそう？
ただ、基本的な考え方は理解していて実装には落とし込めるけれど、ドキュメントへの落とし込み方がうまく掴めていない。
ということであれば、その落とし込み方さえわかれば無双できる可能性あるのでは…？🤔
心当たりがある方は、ぜひ意識して伸ばしてみてはいかがでしょう。
自分も設計〜実装力を合わせて磨いていくぞー。
さらなるテクニカルライティングの世界へ#
自分はこの書籍をとっかかりに、よりテクニカルライティングへの関心が高まったように思います。
他にもテクニカルライティングを取り扱った文献を読んでみたいなぁと。
ちなみに現在は、先日発売されたばかりのこちらの書籍を読んでいます。
架空のサービスのドキュメントを作るような形式で話が進んでいくので、より開発寄りの書籍ですね。
内容が気になる方は、翻訳者の方による紹介スライドがおすすめです。
（プロダクト開発と同じ流れなんだよ、という話があって自分が思ったことは割と合ってたんだーって感激しました）
サイボウズの仲田さんのスライドもおすすめです。
Google のテクニカルライティングのドキュメントはこれから読みたい。
それとテクニカルライティングの資格もあるそうなので、そちらもちょっと気になっています👀
世の中にはテクニカルライターという専門職の方もいらっしゃるので、そういった方々には敵わないかもしれませんが…。
テクニカルライティングは、1エンジニアとして身につけて損はない技術だと思っているので、ぜひ伸ばしていこうと思っています。
せっかく周りから評価してもらえた部分ですし、これからも自分の長所とできるようにしたいものです。
ただ、最近勢いのある AI にとって代わられる可能性のある領域かなとも思いますので、上手い付き合い方も考えていかないとですね。
今回は初めて書籍の紹介記事を書いてみました。
内容を書きすぎると営業妨害になりそうで、薄すぎても何が良いのか伝わらなくなりそうで。
書くの意外と難しい…。拙い文章で恐縮です。
（この記事でこのテクニック活用されてないじゃんとかツッコミがやや怖いですね）
今回紹介した書籍であったり、テクニカルライティングに関心を持ってくれる方がいらっしゃれば幸いです。
ドキュメントは軽視しちゃダメですぞ。