誰にでも分かりやすく、信頼できるドキュメントの存在は、プロダクト開発を円滑に進める上で不可欠だ。

2023年3月11日に発売された書籍『エンジニアのためのドキュメントライティング』（日本能率協会マネジメントセンター）を翻訳し、自身もエンジニアとしてさまざまな開発ドキュメントに触れてきた岩瀬義昌さんは、「プロダクトが育つ開発組織には、優れたドキュメントとドキュメントを尊重する文化がある」と話す。

では、プロダクト開発を成功に導く「優れたドキュメント」とはどのようなものなのか。また、そんなドキュメントが存在する組織は、そうでない組織とどんな差が生まれるのか。岩瀬さんに話を聞いた。

書籍『エンジニアのためのドキュメントライティング』翻訳者
人気ポッドキャスト『#fukabori.fm』運営者
岩瀬義昌さん（@iwashi86）
東京大学大学院修士課程修了後、2009年にNTT東日本に入社。大規模IP電話システムの開発などに従事したのち、内製、アジャイル開発に携わりたいという思いから14年にNTTコミュニケーションズSkyWay開発チームに転籍する。 20年には組織改善に尽力すべく、ヒューマンリソース部に異動。22年からは再び開発部に戻り、全社のアジャイル開発・プロダクトマネジメントを支援。現在は、同社のイノベーションセンター テクノロジー部門 担当課長として活躍。23年3月に発売された書籍『エンジニアのためのドキュメントライティング』を翻訳。エンジニアに人気のポッドキャスト『#fukabori.fm』も運営

優れたドキュメントは、ユーザーの課題解決につながり、生きている

ーープロダクト開発を成功に導く「優れたドキュメント」にはどのような特徴がありますか？

優れたドキュメントには、大きく二つの特徴があります。

一つは、ユーザー（ドキュメントを使う人）の課題解決につながる内容であることです。

良いドキュメントの例として紹介したいのが、Flutter（フラッター）というモバイルアプリ用のフレームワークのドキュメントです。Web上に公開されているので、ぜひ見てみてください。

Flutterのドキュメントに関して私がすばらしいと思うのは、読むにつれて必要な知識が徐々に積み上がっていくように設計されており、ユーザーが「分からないな」と思う部分に対してはきちんと説明がなされているところです。まさに、「かゆい所に手が届く」構成になっています。

サンドボックスを用意するコストは決して少なくないのですが、利用するユーザーが非常に多いことを考慮すると、十分にペイしていると考えています。

「ユーザーの課題解決」という目的意識のもと作成したからこそ、こうした質の高いドキュメントが生まれたのではないかと思います。

また、優れたドキュメントの二つ目の特徴は、「生きている」ということ。つまり、常に最新の状態が保たれたドキュメントであるということです。

変化の激しいIT業界では、言葉の定義やシステムの仕様がすぐに変化します。それらがドキュメントに反映されないままでは、後に読んだ人が「書いてある通りにやったのに動かない！」などとフラストレーションを溜めてしまうでしょう。

ここにある情報は正しい、とみんなが信じている状態のことを「Single Source of Truth (SSOT)」と言うのですが、ドキュメントは常にそうした状態に保たれる必要があります。聞いたところによると、あるSIerの中ではこうしたドキュメントは、“神様ドキュメント”と呼んでいるそうです（笑）

ーーそのような優れたドキュメントは開発組織にどんなメリットをもたらすのでしょうか？

情報の伝達効率が圧倒的に高まり、開発をスムーズに進められるようになります。

もちろん口頭でもドキュメントの内容を伝えることはできますが、それを繰り返すのはあまりにも非効率です。

例えば、ある開発者が社内用APIを開発し、その使い方を知りたい人たち全員が開発者に話を聞きに来たとしましょう。その場合、全ての人に情報が行き渡るまでにかなりの時間がかかりますよね？

ところが、そのAPIの仕様や作業内容がきちんと書かれたドキュメントさえあれば、会話量は最低限で済みます。コミュニケーションコストが大幅に削減されることは、組織にとっての最大のメリットです。

さらに、ドキュメントを書く作業によって自分自身の知識が整理されるというメリットもあります。理解が曖昧だった部分が、人に見せるための文章を書くことによって明確化されるのです。

ーー逆に、ドキュメントづくりや維持に重きを置いていない開発組織が抱えるリスクは？

今回私が翻訳した書籍の中には「ドキュメントを書かずにサービスが成長した結果、ある人のスケジュールは、毎日同じことを聞かれるミーティングで埋め尽くされるだろう」という一説があります。この状態は明らかに非生産的で、組織にとってもリスクと言えるのではないでしょうか。

ドキュメント作成は一見面倒な作業に見えるかもしれませんが、組織にとっても個人にとっても、取り組む価値は非常に大きい作業だと言えるでしょう。

ーードキュメントは作っているけれどそれがうまく機能していない場合、どのような原因があると思いますか？

最も考えられる原因は、ドキュメントづくりを形式的にやっているだけで、ドキュメントをつくることの意味・意義を本質的には意識できていない「開発組織がドキュメントに価値を置いていない」ということです。

世の中には「コードを見れば全部分わかるでしょ」といったストロングスタイルな開発者も存在しますが、今回翻訳した書籍の中ではむしろ失敗パターンとして挙げられています。名著である『A Philosophy of Software Design』の中では、そうした考え方は「神話」だと一刀両断されています。

特に開発の背景や思想などの情報は、コードから完全に読み取るのは難しいでしょう。

ところが開発組織がドキュメントの作成・管理に価値を置いていなければ、開発者はそのための時間を割こうとしません。

マネジメント側もメンテナンスコストを開発スケジュールに組み込まない。そのような組織では、ドキュメントの作成・管理の仕組み化は当然行われません。

「生きたドキュメントを残す」Googleの仕組み

ーー優れたドキュメントの作成・維持で、プロダクトを発展させた企業の事例があれば教えてください。

まず、今回の書籍でも言及のあるGoogleは素晴らしい事例の一つだと思います。

同社はドキュメントごとに「ドキュメントオーナー」を割り当てており、一定期間がたつと「このドキュメントの情報は最新ですか？」とリマインドする仕組みを設けています。

また、外向けのドキュメントであれば、ドキュメントを読んだ人がその記事が役立ったかどうかを評価するYes・Noボタンを設置するなどして、さまざまなメトリクスを測定し、ドキュメントの有効性をチェックしています。

その結果、「必要ないドキュメント」だと判断されれば、不要なものとして削除することもできます。

このように、生きているドキュメントだけを残す仕組みがある企業では、自然とドキュメントに対する信頼性が高まるでしょう。

ーーそうした仕組みを導入し、十分に機能させるためには、まずは開発組織内でドキュメントの重要性が共有されることが大切ですね。

その通りです。その際に注意すべきなのが、ドキュメント作成自体を目的にしてはいけないということです。

残念ながら、世の中には読んでも何も解決しない「中身のないドキュメント」が大量に存在します。

当たり前ですが、ユーザーの課題を理解しないまま「ただ作成すればいい」という意識のもと生産されたドキュメントが、誰かの役に立つことはありません。

ドキュメントの作成・管理は、単なる作業としてではなく、「ユーザーの課題解決につなげる」という目的をきちんと理解した上で行われる必要があります。

ーー岩瀬さんがこれまでに見た中で、最も影響を受けたのはどんなドキュメントでしたか？

前職でエンタープライズ用のシステムを開発をしていた時に読んだドキュメントです。

そのシステムは非常に大規模で、開発当初からシステムに関わった人の数は、上流から下流まで全て含めるとおそらくのべ1万人を超えていると思います。自身のドメインに集中する箇所を絞ったとしても、目を通さなくてはならない仕様書の数は膨大でした。

幸い、各ドキュメントは最新の状態に整備されていたのですが、あまりにドキュメントの数が多かったため、私は各ドキュメントに書かれた情報を「点」としてしか理解することができませんでした。

そんな時に先輩から教えてもらったのが、（読んだ）当時から5年以上前に作成されたドキュメントです。そこには、システムアーキテクチャの設計思想や背景がまとめられていました。

それを読んだ瞬間、自分の中の点だった知識がババッとつながり、なぜシステムがこのような設計になっているのかを一気に理解できるようになりました。

過去の経緯だけでなく、それを踏まえて将来どう拡張するべきなのかという未来を見通す上での示唆も得られました。

ドキュメントのボリュームは数百ページに及びました。おそらくシステムの最初の設計に関わった人たちが書いたのだと思いますが、その作業は非常に大変だったはずです。

重要な情報を残すために、開発者たちがドキュメントを作成する労力を惜しまなかったこと。

そしてそのドキュメントが、常に最新の情報にメンテナンスされる環境があったこと。こうした条件が整っていたからこそ、正しい方向性で開発を進めやすくなっていたと感じています。

チケットには、ドキュメントの質を上げるヒントが詰まっている

ーープロダクト開発を成功に導くドキュメントを書けるようになりたい人は、まず何から始めたら良いでしょうか？

一番大切なのは、ユーザーの課題理解に十分なコストをかけることです。

例えば、「ここがバグってて動かないです」とか「このページが重いです」など、チケットにたまったユーザーからのフィードバックにはきちんと目を通すことが第一歩です。

特にイライラ度合いが強いユーザーは熱いチケットを書いてくれるので、ユーザーが何に困っているのか、どこにつまづいているのか理解が深まります。

同時に、自分自身のユーザー目線を養う努力も必要です。

そのためにはユーザーの一次情報に触れるのがベストですが、それが難しければ「ユーザー目線になっている」と社内で評価されている人と会話を重ねるのが良いでしょう。それによって、自分自身の視野が広がったり、視点が引き上げられたりすることがあると思います。

ーーユーザーの課題解決につながるドキュメントを書けるようになるには、まず自分自身がユーザー目線を身に付けることが大切なんですね。

それに加えて、「知識の呪い」*を突破することも必要です。

ドキュメントの作成者はユーザーよりも圧倒的にその知識に詳しいため、つい前提となる知識を省略してしまいがちです。

するとユーザーが前提となる重要な情報を認識できず、ドキュメントは本来の機能を果たせなくなってしまいます。

こうした事態を避けるためには、自分以外の人にドキュメントを読んでもらうのが一番だと個人的に考えています。

開発者はユーザーにとって分かりにくいと思われることを無意識に記してしまうことがあるので、一度客観的な目線でチェックする時間を持つ必要があります。

また、自分自身が何も知らないユーザーの気持ちになって、ドキュメントに記した作業を追体験してみるのもおすすめです。手順通りにやってもうまく進まない部分があれば、修正を加える必要があるということです。書籍ではフリクションログという名前で紹介されています。

そして、今回の話を通じてドキュメントの重要性を理解していただけた方には、ぜひ良いドキュメントの書き方の学習にチャレンジいただきたいと思います。

ドキュメントの書き方を正面から学んだことのある人は、実はあまり多くはないのではないでしょうか？

身近な人から教わったり、過去に書かれたドキュメントを読んだりして、場当たり的に学んできた人が大多数だと思います。

一度腰を据えて、良いドキュメントとそうでないドキュメントの違いをしっかりインプットすることで、プロダクト開発はずっとスムーズに進むようになるはずです。

取材・文／一本麻衣　編集／玉城智子（編集部）

書籍紹介

「ドキュメントを書いておけばよかった」

開発者であれば一度は思ったことがあるかもしれません。

ドキュメントは開発側の生産性とユーザーの利便性を高めるものです。さらに言うと、ドキュメントがなければ、ユーザーに使われる機会が確実に減ります。開発者がいかにすばらしいプロダクトを作ろうが、ドキュメントの欠如がその価値を奪うのです。

本書は経験に長けた執筆者たちがドキュメントを作成する方法をゼロから説明するフィールドガイドです。架空のソフトウェア開発チームのストーリーを追いながら、ソフトウェア開発ライフサイクルの各ステップにおいて、ユーザーニーズの理解、開発者に役立つドキュメントの作成、公開、測定、保守に至るまで、開発を最適化するためのドキュメント作成の技術を解説しています。

これまで学ぶ機会のなかったREADME、APIリファレンス、チュートリアル、コンセプトドキュメント、リリースノートなど、さまざまな種類のドキュメントの書き方について学ぶことができる一冊です。ドキュメントを作成している現場のエンジニアやテクニカルライター、プロダクトマネジャーの方に最適の内容です。

【著者】
ジャレッド・バーティ（Jared Bhatti）
ザッカリー・サラ・コ―ライセン（Zachary Sarah Corleissen）
ジェン・ランボーン（Jen Lambourne）
デービッド・ヌーニェス（David Nunez）
ハイディ・ウォーターハウス（Heidi Waterhouse）

【翻訳】
岩瀬義昌

＞＞＞詳細はこちら