社内技術ドキュメントで「このページはなに？」を書くすすめ

こんにちは！電通デジタル開発部エンジニアのリチャードです。この記事では、エンジニアが社内技術ドキュメントを書く際、「このページはなに？」というページごとの目的を記載することの有用性を紹介します。

ここでいうページとはWebページのことで、相互にリンクし合うページの集まりとして構成する社内技術ドキュメントを本記事では対象としています。本記事で対象としないものの例は、1つの巨大なPDFファイルで構成された技術ドキュメントなどです。

ただページに情報を残すのではなく、「このページはなに？」を書いて目的をはっきりとさせることで、「どんな読み手を想定するか？」と「読み手にどんな価値をもたらすか？」を考えることを促します。

さらにページの目的をはっきりさせることで、

- ページの中で説明不足な部分が分かりやすくなる
- 反対に書く必要がないことも分かりやすくなる
- ページ分割の必要性を判断しやすくなる

といった効果も期待でき、ページ内容の良し悪しが判断しやすくなります。

ページの目的がないドキュメントはどうやってダメになっていくか

目的が意識されていないドキュメントは、書き手の頭の中をただ書き出すだけになってしまいがちです。そうなると書かれる情報の粒度もバラバラで、必要な情報が欠けている一方、不要な情報が入ってしまうなど読み手の理解を邪魔してしまいます。

個人的な経験ですが、過去に所属した会社ではページの目的が記載されていない社内技術ドキュメントを数多く目にしてきました。冒頭からいきなり手順の説明や技術的な詳細の説明が始まり「そもそもの背景が分からない」「もっと先に知りたい情報がある」というモヤモヤを抱えながら読み進め、結局読み終わっても何が書いてあるか理解できなかったものがほとんどでした。

しかし目的が書かれているからといって、必ずしもそのページが良いものになるとは限りません。過去に私が見た残念な目的設定の例では、開発チームのテスト戦略を記載したページに、

「目的: 必ずテストを書きましょう！！」

とだけ書いてあって、その後すぐ詳細なテスト記述のルールを説明していたので、どういう経緯でテストのルールを導入し、また何を重視してルールが選ばれたのか分かりませんでした。その現場ではテスト不足であることは明らかだったので、それを正そうという強い気持ちが文章に表れたのでしょうが「必ずテストを書きましょう」というだけでは何の説明にもなっていません。

もしそのページが読み手を「チームの仲間とともにテスト戦略を作っていきたいメンバー」と想定し、

「このページはなに？ここではチーム内で合意した最新のテスト戦略とルールを記載しますが、記載されたルールは上から押し付ける絶対的なものではありません。明文化によってチーム内で具体的な議論を促し、常により良いテスト戦略へと更新し続けることがこのページの目的です。」

という目的が設定されていたら、普段からメンバーに「現在のテスト関連ルールは本当に自分たちにとって最良か？」を考えることを促せていたはずです。

このように、読み手に対して望ましいコミュニケーションを促すこともページの目的を書く理由の一つです。ドキュメントはただ読むだけで完結するのではなく、コミュニケーションを促すという側面を意識すると、ページの目的を考える際のヒントになります。

「このページはなに？」を書くときのポイント

先ほどの「テスト戦略ページ」を対象として「このページはなに？」を書く際に気を付けるポイントをもう少し細かく見ていきます。

まずは読み手を想定することです。先ほどは想定する読み手を「チームの仲間とともにテスト戦略を作っていきたいメンバー」としました。それ以外にも、チーム内でテストを書く習熟度に大きな差がある場合、「テストを書くことに慣れていないメンバー」を対象に入門的な内容を多く書くことも考えられます。あるいは全社的な指令でテスト整備をしっかり行わなければならない場合、自分たちのチームのテスト戦略を「会社の上層部」に向けて説明する必要があります。

想定した読み手を1人に絞れず、複数の読み手を想定しなければならない場合は、読み手ごとにページを作成するのも一つの方法です。そうすれば各ページの分量を抑えて情報を伝えやすくできます。

想定する読み手が決まったら、その読み手にどんな価値をもたらすページなのかを考えます。社内技術ドキュメントは開発メンバーが作成に時間を割くので、単に情報を残すだけではなく、明確な価値がないと労力に見合いません。

ページがもたらす価値が思い付かなければ、具体的な利用シーンを想定すると良いでしょう。テスト戦略のページなら「テストを書き始める前に読むのか？」「テストケースの抜け漏れを確認するときに読むのか？」「テストコードのレビュー時に読むのか？」といったものが考えられます。それぞれのシーンで、テスト戦略のページがあることで、想定する読み手はどんな嬉しいことがあるのか？というのが目的を考えるヒントです。

「このページはなに？」を書くことで期待できる効果

本記事の冒頭で「このページはなに？」を書くと期待できる、以下の3つの効果を紹介しました。引き続きテスト戦略のページの例について、これらの効果がどう現れるか見ていきます。

- ページの中で説明不足な部分が分かりやすくなる
- 反対に書く必要がないことも分かりやすくなる
- ページ分割の必要性を判断しやすくなる

ページの目的は先ほどと同じこちらを採用します。

「このページはなに？ここではチーム内で合意した最新のテスト戦略とルールを記載しますが、記載されたルールは上から押し付ける絶対的なものではありません。明文化によってチーム内で具体的な議論を促し、常により良いテスト戦略へと更新し続けることがこのページの目的です。」

もしこのページに「必ずユニットテストを書いてください」というルールの記述があったとすると、具体的なテスト戦略改善の議論を促すには少し説明不足です。それよりは「公開メソッドはユニットテストを書いてください」と書いたほうが「なぜ公開メソッドだけなのか、非公開メソッドはテストしなくて良いのか？」といったテスト戦略の方向性を問う議論を促せます。

あるいは「テストフレームワークの選択理由」と「テストフレームワークのセットアップ手順」の両方が同じページに記載されていたとします。前者は選択理由について議論がテストに関する認識を深める助けになりますが、後者のセットアップ手順については議論の余地はないので、同じページに記載する必要はありません。別ページに移動する方が目的に沿っています。

ページの目的と説明対象の目的を分ける

ある程度文章量の多いページを書くなら、ページの目的である「このページはなに？」と説明対象の目的を分けると、それぞれがより明確になります。

ここでいう説明対象とは、「テスト戦略ページ」の例だとテスト戦略そのものになります。その目的は「ソースコードの品質の向上、開発速度の維持」といったものが典型的で、これはページの目的である「明文化によってチーム内で具体的な議論を促し、常により良いテスト戦略へと更新し続ける」とは異なります。

他の例も合わせて見た方がこの使い分けは分かりやすいと思いますので、以下をご覧ください。

上記の例ではページの目的と説明対象の目的を分けたものを紹介しましたが、必ずしもその方が良いというわけではありません。とくに分量が少ないページでは、わざわざ2つの目的を分ける意義は薄くなります。

ページの目的が必要ない場合

ここまでに紹介してきたように、基本的にはページの目的を考えた方が読み手に届ける価値が明確になり、ページの更新も行いやすくなるので、内容も洗練されていきます。しかし、ありとあらゆる社内技術ドキュメントにページの目的を書く必要があるわけではありません。

例えばメモ書き程度の情報を共有する時は、念入りに目的を検討するよりは素早く思いついた情報を書き出すことに価値があるので、いったん目的設定を忘れた方が書き出す手は止まりません。

その他の例として、作業手順書や障害報告書など、同じ形式と目的を持つページが多数あるならば、その全てのページで目的を記載する必要はありません。

まとめ

以上「このページはなに？」を書くことについて説明してきましたが、いきなり全てのページに目的を書き始めるのは大変なので、無理のないペースとタイミングで目的を書けそうなページから書いてみてください。これはいわゆるオプトイン方式で、複数のメンバーがその有用性を感じてくれたら、自然と習慣が広がっていくはずです。

目的を意識して社内技術ドキュメントを書くことは、伝わりやすい文章を書くトレーニングになります。ぜひ社内技術ドキュメントの質を上げる手段の1つとして検討してください。