「ドキュメントの書き方」を体系的に学んだことがないエンジニアへ　書籍『エンジニアのためのドキュメントライティング』の概要

本セッションの対象者と、セッションのゴール

岩瀬義昌氏：ご紹介いただきました、岩瀬と申します。よろしくお願いします。『ユーザーの問題解決とプロダクトの成功を導く　エンジニアのためのドキュメントライティング』は、もともと『Docs for Developers: An Engineer’s Field Guide to Technical Writing』という洋書だったんですが、その翻訳をして、今回この機会をいただいています。

余談ですが、APC（株式会社エーピーコミュニケーションズ）さんが「カプセルトイ」を作られていたんですね。めちゃくちゃ評判が良くて、「めちゃくちゃほしかったです」ということだけ言ってから始めたいと思います（笑）。

さっそく中身にいきましょう。今日は「30分でわかる『エンジニアのためのドキュメントライティング』」ということでペルソナを少しおさらいしておくと、今回のトークはこんな人向けになっています。（スライドを示して）エンジニアであれば「あー、ドキュメントを書いておけば良かったなぁ」となった経験が、おそらく1回や2回はあるんじゃないかなと僕は思っています。正直僕はけっこうあります。

ただ一方で矛盾があって、「そういえば、ドキュメントの書き方って体系的に網羅的に学んだことがないよね」みたいな方もけっこう多いと思っています。もちろん社内などの研修はあるかもしれないですね。

今回はそういうものを学んだことない方向けの本になっています。イベントの残り30分程度で話をしますが、一部、特に私が重要だと思った部分を紹介していきます。時間があればプラスαのところも少しおさらいさせてもらえればいいかなと思っています。

（スライドを示して）今日はこの対象者に向けて、「30分後にドキュメントライティングのスキルがちょっとでも高まっていればいいかな」ということをゴール地点として狙っています。

この（ドキュメントライティング）スキルって何かというと、例えば「ドキュメントライティングってこうやって書いたらいいんだ」という概要を知っているとか、ドキュメントって準備・作成・運用で、作る前に何かしら仕込んで実際に書いてみて、リリースしてみてという普通のフェーズがあるので、ここで何に気をつければいいのかという重要なポイントを理解することを狙っていきたいと思います。

今回は洋書なので、日本語特有の観点がぜんぜんないんですよね。先ほど言ったプラスαは、時間が余ったら私的に推したい部分があるので、紹介していきます。

岩瀬氏の自己紹介

私の自己紹介をぜんぜんしなかったので一瞬だけ自己紹介すると、名前は岩瀬義昌と言います。Twitter（現X）は@iwashi86でやっているので、よければフォローしてもらえるとありがたいです。

本業は通信企業でプロダクトマネジメントやアジャイル開発をしていて。また（それとは別に）組織支援とかもいろいろやっています。サイドワークも本当にいろいろやっていて、その中の1つで翻訳者として洋書籍を翻訳しています。

（スライドを示して）一番下に書いてある「ポッドキャスター」は、私の（やっていることの）中ではたぶん一番よく知られているものだと思っていて、fukabori.fmというテックポッドキャストをやっています。実際にこの本の著者にも出てもらっているので、英語なんですが、もし興味があれば聞いてもらえるとおもしろいエピソードがあります。書籍には実はコーギーの犬が出てくるんですけど、「それはもともと『カウボーイビバップ』から来た」みたいな裏話も（fukabori.fmの中に）あるので、興味があればどうぞ。

セッションのアジェンダ

ということで本題に入っていきましょう。今日の本題は、先ほど言ったとおり、ドキュメントの概要をしゃべっていきます。（スライドを示して）上からざっといくと、書籍の概要をしゃべった上で、特に翻訳者視点から「ここは意識してほしいな」というところを4章ほど紹介します。最後に時間があればプラスα。さっそく上からいきたいと思います。

書籍の概要

書籍の概要です。ではさっそくいきましょう。書籍を書くにあたって、概要はパート1、パート2、パート3の3つに分かれています。パート1はドキュメント作成の準備というところで、実際に読み手は誰なのか、どうやって作ったらいいのかと計画していく部分が最初のところです。

2つ目のところが実際に書いていくドキュメント作成の部分で、これが3章から6章になっています。ドラフトは下書きみたいな感じですね。3章は下書きを書いて、下書きをさらに編集して精度を上げていって、必要であればサンプルコードを入れて、あとは図表とかを入れるみたいな流れになっています。

最後のパート3は何を書いてあるかというと、書いたらリリースで出すじゃないですか。ドキュメントはリリースしても終わらないんですよ。プロダクトと一緒ですね。リリースはむしろスタート地点で、公開したらフィードバックをもらって、その品質を測定してより良くするにはどうしたらいいのかということを考えます。

それでさらにものが増えてくると、ドキュメントがたくさん増えて探すのが大変になるので、構成全体のリファクタリングをしないといけないとか……。それ（書いてあるの）が10章ですね。

最後の11章が、ドキュメント保守と非推奨化です。これはデプリケート（deprecate）です。ドキュメントも最後はなくなるので、最後のなくなるプロセスまでが書かれているのがこの章になっています。

今日はこのうちの1、3、8、9章を特にちゃんとしゃべります。

ここ（の4つの章）に注力するので、他のポイントは先ほどしゃべったとおりで、基本的にはサラッとしか書いていません。資料はハッシュタグで放流しようと思うので、もし興味があれば、読んでもらえれば全体の概要の概要ぐらいはわかるかなと思います。

作成の部分も先ほどと同じく言ったとおりで、ドラフトを書いて精度を上げるプロセスです。

最後のパート3に関しては、何かを出してリリースして改善していくところになっています。

ドキュメント作成の流れは、プロダクト開発とまったく同じ

ここで言いたいのは別のことで、これはプロダクト開発とまったく同じことをやります。ドキュメントに関しても、プロダクトの1つなんですよね。プロダクトを作る時には、最初にユーザー理解をするじゃないですか。「どんな課題を解きたいのか」を理解していく。どういうユーザージャーニーをたどっていくのかを計画していきますよね。

そしたら、（出来上がった計画は）あくまで仮説でしかないので、仮説検証しにかかるんですよ。そのために我々は実際にプロダクトを開発する。ソースコードを書いてレビューをして、プロダクトを作っていく。それができたら外に出して、リリースして、反応を見る。（そうすると）ユーザーから必ずフィードバックが何らかある。「ない」というのもフィードバックの一種ですね。ユーザーからのフィードバックがないのも別の問題があるはずです。

さらに使われていない機能をプロダクトから消す。ソースコードから消すと気持ちいいですよね。重要ですが（これは）ドキュメントも一緒で、不要な機能を減らしていくのはとても大事なので、それもやっていきます。

そうするとまたユーザーの理解が進むわけなので、またユーザー理解に戻って、「こんなことを書いていけばいいんじゃないか」ということを計画していくということをグルグル回すのがプロダクト開発の流れになっています。

「ドキュメントでもまったく同じことを扱いますよね」ということが書かれているのがこの本です。全体像が書かれていて超細かいところは書いていないんですが、少なくとも最初から最後まで（の全体）を知れる本だと思ってもらえればいいかなと思います。

本書籍を読む上での注意点

（スライドを示して）さっそく中に入っていきますが、1点だけ注意点があるのでちょっとだけおさらいさせてください。何かというと、この本はエンジニアが作る・使うドキュメントに集中している書籍です。だから「どうやってパラグラフを構成させればいいですか」みたいな、ドキュメントのロジカルライティングやパラグラフライティングと言われたりするものに関しては、まったく触れられていないです。

（そのあたりのことは）もう知っていることが当たり前な本になっているので、（その前提部分のことに）もし興味があれば、私が良いなと思っている本を3冊ほど右下に書いておいたので、合わせて読んでもらえると、文章力は非常に上がるかなと思います。

『理科系の作文技術』とか『ロジカル・ライティング』、また『考える技術・書く技術』とかの新版など、いろいろなものも出ているので、見てもらうといいかなと思います。ご参考までにどうぞ。

（次回につづく）