このメモは、私（@ymmt2005）が長年にわたってソフトウェアプロダクト開発に関わってきて 2022年現在こうしたほうが良いと考えているベストプラクティスです。
科学的な分析等に基づくわけではない経験則であるため、今後も随時見直すことがありますし、 ここに書いてあることが常に正しいわけでもあらゆるソフトウェア開発に適するわけでもありません。
しかしながら、実務経験が豊富で、モダンな技術スタックに明るいエンジニアの経験則は一定の 役に立つのではないかと考えて記します。
ここでは、ソフトウェア開発で技術者が書くべき文書ということにします。 ソフトウェアエンジニアにも役割がいろいろあり、アーキテクトと independent contributor では書く文書が違うということはあるでしょうけれど、ここではごっちゃにします。
私がしばしば書く文書の種類は以下です。よく書く順に並べています。
-
README.md
リポジトリのルートディレクトリ、もしくは各ディレクトリに README.md を置くのは今日非常に一般的です。 ソフトウェアの利用者や開発者がまず目にする文書なので、ここに各種の情報をコンパクトにまとめておくと スムースなユーザー体験につながります。
-
新規にソフトウェアを書き起こすときには、必ず設計文書（Design Docs）を書いています。 設計文書には、最低限「解決したい課題とその背景」「実装することになる予定の機能」「実装方針」を書きます。 リンク先に Google での Design Docs の書き方がありますが、決まりというほどのものではないので参考 にしつつ、自由に書いてよいです。
例：https://github.com/cybozu-go/accurate/blob/main/docs/design.md
-
Specifications / API docs
実際に開発したプログラムやライブラリの外部仕様は、必ず文書化しています。利用者にとって必要ということも ありますが、仕様書をプログラムの前に書くことで実装の見通しが立ち作業しやすくなることもしばしばあります。
こういった外部仕様書は、可能であれば自動生成することを第一に考えましょう。プログラム言語の API であれば コメントから markdown や HTML 形式の文書に出力する方法があるのが普通です。ネットワークプロトコルの場合も、 gRPC / Protocol Buffers などを使うことで自動生成できます。
例: https://github.com/cybozu-go/moco/blob/main/docs/metrics.md (Prometheus 形式のメトリクスの仕様書、手書き)
-
User guide
プログラムの利用者向けの文書です。といっても、利用者が一般大衆の場合は専門の tech writer が書くでしょうから、 ここでいう User guide は利用者がソフトウェアエンジニアであるようなプログラムのマニュアルを指しています。 網羅性よりは、利用者が頻繁に使うであろう機能を中心に実行例などを添えてわかりやすく書くことが大事です。
例: https://github.com/cybozu-go/moco/blob/main/docs/usage.md
-
Random memo
プログラムの開発中に、難しい処理が必要な場合にまずドキュメント上で検討したりします。あるいは結果的に複雑に なってしまった処理をチームのほかの人や未来の自分が理解しやすい形で解説したりします。そういう時に作るメモ類 も大事な技術文書です。
以下の例は、MySQL のクラスタを自動管理するアルゴリズムや取りうる内部状態といった内部仕様についてのメモです。
例: https://github.com/cybozu-go/moco/blob/main/docs/clustering.md
-
Architectural Decision Records (ADR)
ADR はアーキテクチャ上の大事な意思決定を文書の形で残して、あとで参照できるようにする目的で書くものです。 リンク先にあるようなテンプレートを使って、選択肢の中からこれこれの理由でこう決めた、みたいな記録を簡単に 書くことができるようになっています。
が、実際には ADR を書くことは多くありません。アーキテクチャレベルの大事なことは ADR のテンプレートで 記述するに収まらないことが多く、より自由な Design Docs として残すことが多いです。細かいレベルの意思決定 になってくると、いちいち記録を残す価値があるかわからないこともあり、ADR を書くに値する意思決定はなかなか 見当たりにくいです。
まあ、それでもテンプレートからさくっと作れるのは手軽でよいです。
文書を書く理由は、大別すれば三つです。
- 自分のため
- チームのため
- 利用者のため
まず、Design Docs は自分のために書き出すことが多いです。あとからチームの人が参照できはしますが、まず第一に 自分がこれから作るソフトウェアのための準備作業の側面が非常に大きいです。
内部仕様などのメモ類と ADR は、チームのために書くことが多いです。細かいことはきっと忘れてしまう未来の自分も含めて。
その他の README.md や User Guide, API ドキュメントは利用者のためです。
それぞれの文書に何を書くか、慣れないうちは迷うかもしれません。 テンプレートや見本がある文書類は、それに従うのが初心者でも書きやすいです。
あとは、以下のポイントを押さえておけばいいでしょう。
- 自分のための文書は、書きたいことを好きなだけ書く。
- チームのための文書は、実際に見てもらって過不足ないか確認する。
- 外部仕様書の類は、網羅していることと正確であることが大事。自動生成を第一の選択肢に。
書くこと以上に大事なのは、ソフトウェアの修正に伴って文書類をメンテナンスすることです。 この点で、ソフトウェアの細かな内部仕様に基づいた文書を手書きすることは、一般的に良いアイデアとは言えません。 もちろん、複雑な処理についてメモを残すことはしばしばありますが、そういうときもソースコードレベルにまで立ち入らない書き方が良いでしょう。
メンテナンスができない文書は、場合によっては削除してしまったほうがましだったりもします。
図や表は理解を促すために大変有用です。 文章では説明しにくいとか長ったらしい場合、図を書くようにしましょう。
図を書くのは慣れないうちは面倒で、なかなか手が動かないかもしれません。 でも昨今は便利なツールが揃っているので、とにかく一つのツールにでも慣れるようにしましょう。
図を含んだ良い文章が書けるエンジニアは、エンジニアとしてレベルが一段上だと思います。
ソフトウェアエンジニアが文書を書くにあたって便利なツールを紹介します。
- Markdown: 皆さんご存じの Markdown。手軽に書けて、きれいに HTML でレンダリングされます。まず第一に覚えましょう。
- Mermaid.js: フローチャート等を書くのにとにかく手軽。GitHub 上なら markdown 内でレンダリングできます。
- draw.io: ドロー系のツールで、GCP/AWS などのアイコンが豊富。SVG ファイル自体をデータファイルにできるため、SVG ファイルを Git リポジトリにおいておけば他の人が draw.io 上で再編集できます。
- mdBook: Rust 製 static site generator。高速でビルドできて見栄えが良いです。
- Protobuffet: gRPC の API を自動生成するならこれが一番きれいだと思います。
- Google Docs / Sheets: エンジニア以外とも共有するときに使っています。Sheets は Glossary などに使うと便利。