ドキュメントを書く時に考えていること

ソフトウェアエンジニアの summerwind です。最近は LLM が自分のふりをして代わりに仕事をしてくれるような仕組み作りを趣味にしています。

先日社内で「ドキュメントをうまく書く方法はありますか？」という質問をもらったのですが、普段ドキュメントを書く時に意識をしている要素のようなものはあるものの、それをちゃんと言語化したことがなかったため、抽象的にしか答えることができませんでした。改めて言語化をしてみるのは面白そうだなと感じたので、今回はドキュメントを書く時に考えていることをいくつか書き出してみたいと思います。

想定する読者を決める

ドキュメントを書く時にまず最初にやるのは「そのドキュメントの想定する読者は誰か」についてを考えることです。よくある想定読者には次のような方々がいます。

同じチームで働くエンジニアのメンバー
同じプロジェクトで働くメンバー
全メンバー

想定する読者が決まると、ドキュメントに書くべき情報は何か、どのような粒度で情報をまとめるべきなのかの検討がしやすくなります。例えば、様々な職種がいるプロジェクトメンバーに向けたドキュメントでは、いきなり技術用語や詳細な仕様の話を出しても理解が難しくなると思うので、アプリの動きや全体的な構成の話から深掘りしていくような流れを作るのがよさそうだ、といった判断ができるようになります。

全体的な構造を決める

想定読者が決まったら、その読者の理解度合いに応じてドキュメントの構造を決めていきます。例えばプロダクトに新しく追加する機能の説明用ドキュメントを書く場合は、背景や前提となる情報の説明から入り、機能の目的や説明、詳細と深掘りしていくような構成を作ります。

きれいな構造を一度にまとめるのは難しいため、まず最初に次のような見出しのリストを作り、ドキュメントに記載が必要と思われる情報をひととおり洗い出します。その後、見出しの順番を入れ替えたりセクションを分割したりというのを繰り返して、ドキュメントを読み進めるごとに詳しい内容が分かるような構成を組み立てていきます。

- 背景
- 前提となる情報
- 目的
- 要件
- 機能詳細
  - フローAについて
  - フローBについて

情報を文章にまとめる

全体的な構造がある程度決まったら、構造の見出しに従って情報を可能な限り簡潔な文章にまとめていきます。文章を書くにあたっては、最初に箇条書きリストで記載するべき情報をまとめ、その後、適切に段落を区切った文章を構成するようにしています。

以下は以前のブログ記事の中で 3D セキュアの説明をするための文章を考えた際の箇条書きリストのサンプルです。

# 3D セキュアとは

- 決済時にカードの所有者であることを事前に認証する仕組み
- 不正利用の防止に役立つ
- 3D というのは三次元のことではなく3つのドメインを指す
  - アクワイアラ、決済ネットワーク、イシュアの3者
- ...

この箇条書きリストをもとにして、次のような文章を書きます。

3D セキュアは、オンラインなど非対面でクレジットカードを使用して決済をする際に、カードの所有者であることを事前に認証する仕組みです。3D セキュアを使用することで、カード情報の盗用によるオンライン上での不正利用を防止できます。ショッピングサイトなどでカード決済をする際に突然パスワードの入力を求められた、といった経験がある方も多いかもしれません。あれが 3D セキュアによる認証です。 ...

自分だけが読むようなドキュメントは、脳内の理解した構造に基づく箇条書きリストでドキュメントを書くことがありますが、他の人に読んでもらうことを想定しているドキュメントは読みやすさを重視した簡潔な文章にまとめるようにしています。これは読み手が必ずしも自分と同じ脳内の理解構造を持つとは限らないと考えているためです。

適切なフォーマットで表現する

文章がまとまってきたら、読者にとって読みやすくなるように適切なフォーマットを使って情報の表現を調整します。

カンムの社内では広く Markdown が使われているため、例えば次のようなフォーマットを使用します。なお、どのような表現フォーマットを使うかについては、書き手の好みによるところが大きいかもしれません。

重要な説明や意識しておきたい単語は必要に応じて太字や斜体を使用して表現します。

3DS 最新仕様は **EMV 3-D Secure** です。
3-D というのは三次元のことではなく3つの *Domain* を指しています。

順序のない項目については順序なしリストを使用します。

- プランA: ...
- プランB: ...
- プランC: ...

手順や流れなどは順序付きリストにまとめます。

1. 最初に A を実行します
2. 次に B を実行します
3. ...

他のドキュメントや Web ページの内容、メッセージなどは引用形式を使用します。

> We choose to go to the moon. We choose to go to the moon in this decade and do the other things, not because they are easy, but because they are hard.

前提となる知識や情報を整理する

新たにドキュメントを書く場合は、最初の方にそのドキュメントを理解するのに必要となる前提知識や情報を可能な限りまとめるようにしています。前提となる知識や情報が多くなるような場合は、前提を説明するための個別のドキュメントを用意することもあります。

例えば、バンドルカードの 3DS の実装に関する詳細設計ドキュメントを書く場合を想像してみます。この実装の説明には以下のような前提知識が必要となるため、ドキュメントの最初の方にこれらの説明や考え方について書いておくようにします。

3DS とは何か
3DS の実装に必要となるシステムは何か

制約条件を整理する

前提となる情報と同様に、設計や手順などのドキュメントを書く際は制約条件も整理して書くようにしています。ここで言う制約条件とは「ドキュメントの書き手の都合では変更できないような事項」のことを指します。制約条件には具体的には以下のようなものがあります。

パートナー企業が管理するシステムの仕様
パートナー企業と合意したスケジュール
法規制やコンプライアンスなどに基づく変えることが困難な要件
社内で確定したスケジュール

これらの制約条件を可能な限り整理しておくと、ドキュメントに書かれた情報の背景を理解する助けとなり、またドキュメントを土台にした設計レビューなどの議論もしやすくなると考えています。

基本的な方針を示す

前提や制約条件、要件などを記載して議論に使用するようなドキュメント (Design Docなど) を書く場合には制約条件や要件をよく考慮した上で基本的な方針を示す内容を書くようにしています。

2023/12 までに機能 X をリリースする
法規制に基づいて機能 Y の追加は必須とする
システム構成の制約によりコンポーネント A に機能 X を実装する

このような基本方針は、ドキュメントの内容をもとにレビューや議論をする際の大枠の合意に役立ちます。もし大枠の合意なしに詳細部分に関する議論に入ってしまうと、大枠部分に方針転換が発生した時に大きな手戻りが発生し、議論が最初からやりなおしになる可能性もあるので、これを避ける意図もあります。

運用時の動きを想定した内容を含める

プロダクトに関するドキュメントを書く際は、できるだけ運用時の動きを想定して、それに関する情報を含めるようにしています。

例えば新しい機能の設計をするためのドキュメントには、不具合発生時の調査を想定してログの出力に関する情報を追加したり、障害発生時に起きる可能性がある問題などについて言及するようにします。何かの操作手順に関するドキュメントを書くような場合には、エラーが起きるケースや入力値のバリデーションなどについて可能な限り言及するようにします。

どこまで運用時の動きを想定できるかは書き手の経験的な部分に依存するかもしれません。最初に全てを書こうとはせず、思いついたタイミングなどに必要に応じてドキュメントを繰り返し加筆するようにしています。

情報の説明と論点や確認事項は明示的に分けて書く

ドキュメントでは情報に関する説明と個人の意向や確認事項を混ぜて書かないように心がけています。これは単純に、ある情報に関する説明の文章の途中に個人の意向や確認事項を混ぜ込んでしまうと、どこまでが事実でどこまでが書き手の意向なのかが分かりにくくなってしまうためです。

ドキュメントを土台に何かを議論したり説明したりする場合は、論点や確認事項を個別のセクションに独立した形あるいは 要確認 といったラベルを付与した単独の段落として記述するようにしています。

一次ソースへの参照を書く

パートナー企業が管理するシステムとの接続のための設計ドキュメントや特定のツールを使った運用手順に関するドキュメントには、システムの仕様書や運用の中で扱うツールのマニュアルといった一次ソースへのリンクを記載するようにしています。これは読者がドキュメントには記載がないより詳しい情報を知りたいと思った時に、関連情報へのアクセス手段を提供することを意図しています。

継続的に更新する

ソースコードの管理と同じでドキュメントも継続的に更新しないと様々な問題が生じていきます。新しい情報や前提が生まれた場合は必要に応じて内容を更新するようにします。ドキュメントの継続的な更新が難しい場合は、すでに内容が古くなったことを明記するなどして読み手が混乱しないように配慮しておくのがよいかもしれません。これに関しては LLM のような新しい技術を活用して、継続的にドキュメントを自動更新していくような仕組みを作れれば、と最近は考えています。