アイキャッチ

“知識の呪い”にかかってない? 優れたドキュメントづくりの第一歩は「読み手を理解する」ことから

働き方

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

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

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

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

    はじめに

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

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

    仮想サービス「Corg.ly」の開発メンバー紹介

    シャーロット
    Corg.lyのリード開発者。1か月後にCorg.lyと開発者向けドキュメントをリリースする役割を担っている
    カーティク
    Corg.lyで働くソフトウェアエンジニアで、シャーロットの同僚
    メイ
    Corg.ly翻訳サービスの初期顧客の一人
    アイン
    コーギー犬。Corg.lyのオフィスのマスコットであり、Corg.lyのベータテスターでもある

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

    ドキュメントライティング

    サービス開始まであと一カ月。

    シャーロットはいら立っていた。Corg.lyのサービス開始まであと数週間しかないのに、最初の一人のユーザーが使えるようにするために、開発者全員、つまり五人の開発者に午後中働いてもらわなければならないからだ。

    シャーロットは、システム図・設計上の意思決定・エンドポイントとのデータ送受信方法を1時間で説明してから、Corg.lyの動きやAPIの使い方をデモした。

    初期顧客であるメイは、とても辛抱強くいてくれた。会社公式の飼い犬でありプロダクトテスターでもあるアインは、ご褒美の犬用ビスケットいくつかと引き換えに喜んで翻訳デモに協力してくれた。

    シャーロットはこのミーティングで費やした時間をふりかえって、こういったミーティングは時間とコストがかかることに気づいた。プロダクトがこの先成長して、たくさんの顧客に使ってもらうためには、顧客自身がすぐにプロダクトを使えなければいけない。

    シャーロットの心を読んでいるかのように、メイは椅子にもたれかかって言った。「実際に動かせるまでに、まだ問題がたくさん出てきそうですね。動き始めたらきっと、質問がもっとたくさん出てくると思います。ドキュメントの準備ができたら、それを送ってもらってもいいですか? すぐにもう一度やってみますよ」

    「もちろんです」とシャーロットは答えた。そのとき、これまで6か月間の場面がフラッシュのように脳裏に浮かんできた。

    「どうせまた変わるんだから、ドキュメントは後回しにしよう」
    「他にやることがたくさんあるから、ドキュメントの優先度は下げておこう」
    「コードを読めば分かるから、ドキュメントは心配しなくていいかな」

    胃に穴があくような気分だ。

    シャーロットの返事に対して、メイは次のように答えた。「ありがとうございます。チームの他のメンバーに共有するのが楽しみだわ。

    ただ、みなさんはエキスパートだけれど、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 のユーザーのゴールは異なります。しかし、1つのドキュメントセット*の中であれば、2つのゴールの整合を取れます。2つのゴール間で異なる部分と重なる部分を明らかにすることは、ユーザーに共感することと、ユーザーのニーズを効果的に満たすことに役立ちます。

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

    *複数のドキュメントのこと

    ユーザーを理解する

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

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

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

    note
    すべてのユーザーが同じわけではありません。ユーザー全員のニーズを満た すのは無理です。ビジネスやプロダクトにとって最も重要なユーザーを優先しましょう。

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

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

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

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

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

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

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

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

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

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

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

    書籍紹介

    iwase

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

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

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

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

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

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

    【翻訳】
    岩瀬義昌

    >>>詳細はこちら

    Xをフォローしよう

    この記事をシェア

    RELATED関連記事

    RANKING人気記事ランキング

    JOB BOARD編集部オススメ求人特集





    サイトマップ