要件定義書、詳細設計書、ER図、テスト仕様書など、エンジニアが書かなければならないドキュメントの種類は数あれど、それらの「書き方」を体系的に学ぶ機会を持ったエンジニアはそう多くないのではないでしょうか。

2023年3月に出版された『エンジニアのためのドキュメントライティング』（日本能率協会マネジメントセンター）は、開発者向けのドキュメント作成の入門書がないことを痛感した著者が執筆した一冊。

複雑かつ変化の激しい開発現場において、ドキュメントを用意することにどんな意味があるのか。優れたドキュメントとはどのように作ればいいのか。同書に掲載された内容から紹介します！

※本記事は、『エンジニアのためのドキュメントライティング』を一部抜粋し、転載しています
※翻訳された岩瀬義昌さんのインタビュー記事はこちら

はじめに

書籍では、「Corg.ly」という仮想のサービスに取り組む開発チームの架空の物語を軸にドキュメント作成のステップが紹介されていきます。

Corg.lyとは、犬の鳴き声を人の言語に翻訳するサービスのこと。Corg.lyには翻訳情報を送受信するためのAPIがあり、翻訳を定期的に改善するために機械学習のモデルが使われています。 書籍を抜粋するにあたって、まずはCorg.lyのチームにいるメンバーを紹介していきます。

仮想サービス『Corg.ly』の開発ストーリー

知識の呪いとは

1980年代後半、「人間は他人が自分と同じ知識をもっていると思い込んでいる」ことをハーバード大学の経済学者グループが発見しました。彼らはこの認知バイアスを「知識の呪い」と名づけました。

その数年後、スタンフォード大学の博士課程の学生が知識の呪いを実証しました。あるグループの被験者に有名な曲のリズムを指で叩いてもらうようにして、その音から別の被験者が曲名を当てる実験をしたのです。指でリズムを叩いている被験者はその曲を聞いたばかりでよく覚えているため、聴く側の被験者は曲名の大半を当てられるだろうと考えていました。

実際はそんなに当てられませんでした。指でリズムを叩く側の被験者は、聴く側の被験者が51%の確率で当てられるだろうと予測していました。しかし、残念なことにわずか2.5%しか正しい曲を当てられなかったのです。

あなたも知識の呪いの被害にあってきたはずです。同僚があなたの耳慣れない専門用語を使ったり、あなたが簡単に見つけられるものと思ってAPIエンドポイントを示し忘れたり、エラーメッセージを示すものの解決に必要な背景情報が示されなかった、といった経験があるかもしれません。

Corg.lyの例でいえば、シャーロットは Corg.ly のプロダクトに多くの時間を費やしてきたので、プロダクトを熟知しています。しかし、最初のユーザーは、どのようにプロダクトを理解すればよいのか分かりません。

呪いを断ち切り、効果的なドキュメントを書くためには、ユーザーへの共感が必要です。ユーザーがそのソフトウェアに求めていることと、サポートが必要になる箇所を理解する必要があります。ユーザー調査を通じて、ユーザーのニーズを十分に理解することで、ユーザーが必要とする前にそれを予測できるようになります。

紙とペンを使ったり、キーボードに手を置いたりする前に、ユーザー調査をすることでユーザーを成功に導けるでしょう。

ここでは、知識の呪いから逃れて、ユーザーを理解する次の方法を紹介します。

・ユーザーのゴールを特定する
・ユーザーを理解する
・ユーザーのニーズを理解し、ドキュメントがそれをどう解決するか理解する
・分かったことをペルソナ、ストーリー、マップにまとめる
・フリクションログを使って仮説検証する

ユーザーの最初のスケッチを作る

ユーザーのために効果的なドキュメントを書くには、ユーザーが誰であって、何を達成したいのか理解する必要があります。

まずは、プロダクトやユーザーに関してすでにある情報を集めて、レビューをするところから始めてください。これらの情報には、昔のEメール・設計書・チャットでの会話・コードコメント・コミットメッセージなどが含まれるでしょう。これらの情報をレビューすることで、ソフトウェアがどのように動くか、ユーザーがそれを使って何をしようとしているのか、より明確なイメージを描けるようになります。

また、あなたの組織のゴールに一致するかどうかは分かりませんが、ユーザーにもユーザー自身のゴールがあります。こうした初期のレビューは、お互いの異なるゴールの間にあるギャップや齟齬の特定に役立ちます。

ユーザーのゴールを定義する

既存の情報を確認したら、ユーザーがドキュメントを読んで達成したいことを理解することが次のステップです。ユーザーのゴールを知ることで、調査の進め方が分かり、最も関連している情報のドキュメント化に注力できるようになります。

考えてみてください。そもそも、なぜドキュメントを書く必要があるのでしょうか？　単にソフトウェアについて知ってほしいからではありません。

ユーザーに何らかのタスクを完了してもらいたい、もしくは何らかの方法で行動を変えてほしいからです。そこにはユーザーにとっての技術的なゴールと、ユーザーにたどり着いてほしいという、あなたにとってのビジネス的なゴールがあります。

シャーロットにとってみれば、Corg.lyのビジネスが成功するためには、できるだけ多くの新規ユーザーが Corg.ly を使い始める必要があります。
Corg.ly のドキュメントのゴールは次のようにまとめられます。

Corg.lyのAPIを新規ユーザーが組み込めるように支援することで、新規ユーザーを獲得してオンボード*する。

一方で、Corg.lyのユーザーの最もよくあるゴールは次のとおりです。

犬の鳴き声を人の言葉に翻訳する。

Corg.ly というプロダクトのゴールと、Corg.ly のユーザーのゴールは異なります。しかし、１つのドキュメントセット*の中であれば、２つのゴールの整合を取れます。２つのゴール間で異なる部分と重なる部分を明らかにすることは、ユーザーに共感することと、ユーザーのニーズを効果的に満たすことに役立ちます。

本章の以降のセクションでは、ユーザーやニーズを調査しながら、大きなゴールを小さなゴールに分割する方法を扱います。しかし、重要なのはビジネスの視点から、ユーザー全体に渡るゴールを最初に定義することです。

ユーザーを理解する

ユーザーが達成したいことを理解したので、ユーザーを特定できるようになりました。ユーザーを定義するための方法はたくさんあります。たとえば、開発者・プロダクトマネージャー・システムアドミニストレーターといった役割によって定義できます。

他には、ユーザーの経験のレベルやドキュメントを読んでいる状況でも定義できます。たとえば、新人の開発者がユーザーでしょうか？　そのユーザーは、朝４時にページャーに起こされてから、ドキュメントを読みますか？

知識の呪いを思い出してください。ユーザーとあなたとでは、もっている知識・スキル・ツールなどが大きく異なるかもしれません。

たとえば、もしあなたのソフトウェアの主な対象が開発者なら、開発者のニーズの理解に集中してください。これはエンジニアリングチームのためにソフトウェアを評価するプロダクトマネジャーのニーズとは対照的です。ユーザーがどんなタイプの開発者なのか考えてみてください。セキュリティと信頼性に重きを置いているSRE（Site Reliability Engineer）と、APIを利用するアプリケーション開発者とでは、求めるものが異なります。

ここまでの問いを考えたら、次はユーザー間で共通する特徴をリストに書き出していきましょう。できるだけ焦点を絞って簡潔に書いてください。開発者がドキュメントの読み手であるなら、次のような項目を考えてみてください。

・開発者のスキル
・プログラミング言語
・開発環境
・オペレーティングシステム
・チームの役割

特徴のリストはユーザー調査を始めるスタート地点となります。調査が進むにつれて、カテゴリを追加することもできます。

ユーザーニーズのアウトラインを作る

ユーザーの基本的な定義と、ユーザーに達成してほしい全体のゴールができたら、ユーザーニーズのアウトラインを作れるようになります。いちばん簡単な方法は、ドキュメントで答える必要がある、ユーザーが疑問に思う質問のリストを作る方法です。

一般に、次に示す質問は、どのプロダクトであっても適用可能です。

・これは何のプロダクト？
・このプロダクトが解決する問題は？
・どんな機能がある？
・費用はどれぐらいかかる？
・どこから始められる？

他の質問はプロダクト、ユーザー、ゴールによって固有なものです。

・APIを使うための認証はどうすれば良いか？
・この機能はどうやれば使える？
・どうやればこの問題を解決できる？

自分自身のプロダクトの経験を通じて、質問のいくつかはすぐにみつけられるでしょう。しかし、知識の呪いを思い出してください。ユーザーはあなたほどプロダクトに詳しくありません。だから、プロダクトに関する基本的な質問に答えることになります。ユーザー調査が進んで、ユーザーの理解を検証できるにつれて、彼らがドキュメントから回答を知りたくなるような質問を追加していけばよいでしょう。

書籍紹介

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

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

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

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

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

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

【翻訳】
岩瀬義昌

＞＞＞詳細はこちら