ぷらすのブログ

ドキュメントの運用を考えてみたが正解が分からない

#開発#ドキュメント

ドキュメント運用について考える機会があったので、そのとき考えてたことをダンプしてみる。 実際に運用しているわけではないので机上の空論だが、文字に起こしてみることで何か得られないかと思いやってみる。

ドキュメントを運用する目的 (WHY)

私がドキュメントを読みたくなるタイミングは大体次のように分類される。

前者は差分を表すドキュメントであり、後者は言わば差分を適用し終えた最新のドキュメントである。

この 2 種類のドキュメントを適切に用意できればハッピーになれるので、これらのドキュメントを継続的に用意することがドキュメントを運用する目的になる。

ここからは本来の意味とは少しずれるかもしれないが、ある時点での意思決定を表すドキュメントをフロー型と呼び、最新の仕様が書かれたドキュメントをストック型と呼ぶ。

考えていること

改めてどういうときにドキュメントを読むのかを考えてみると、前者は実装のタイミングで読むのに対し、後者は実装前のフェーズで読むことが多いという発見があった。

これは GitHub 上で開発をしていることを考えると、差分である PR を作るときに差分のドキュメントが欲しくなり、PR を作る前の段階で最新の仕様を知りたくなるのはとても自然に感じる。

逆に言えば、差分が知りたいのに差分がなかったり、その逆がなかったりすると、開発フローとドキュメントの相性が悪くなり、「欲しいドキュメントがない」という状態になってしまう。そのため、ドキュメントを運用を頑張るなら GitHub の開発フローとうまく噛み合った運用フローを考える必要がありそう。

目的を達成する上で実現したいこと (WHAT)

共通

フロー型ドキュメント

MUST

WANT

ストック型ドキュメント

MUST

WANT

ソフトウェア開発において最も貴重なのは人間なので、人間の工数はできるだけ吸い取られないようにする。できるだけ機械に寄せていく。

考えていること

フロー型のドキュメントは書くときはトップダウン(執筆 → 実装)の流れになり、読むときは(実装 → 執筆)の流れになることが多い。そのため、フロー型のドキュメントはコードから検索できるようにするようにするのが望ましそう。

また、フロー型のドキュメントはストック型に比べて存在することが大事なので質より量が大事なので量が多くなる。そのため、テキスト検索では目的のドキュメントを見つけるのは難しい。もちろん検索システムが優れているドキュメント管理サービスを使えば良いが、そもそもコードを読んでいるときにドキュメントを読みたいのであれば、コードから直接検索できるようほうが合理的に感じる。

ストック型のドキュメントを常に最新のドキュメントを維持するのはとてもコストが高いので、できるだけ自動化できるようにし、自動化できないものは人間の手によって更新し続けられる仕組みを用意する。それができないものはフロー ß 型として管理するようにしたい。 そうなると、必然的にストック型のドキュメントの量は減っていきそう。 これは検索性が上がり、最新のドキュメントに保つコストが減るのでポジティブに捉えて良さそう。

ドキュメントの管理方法 (HOW)

フロー型ドキュメント

まとめると、"コミットから辿れれば何でもええや"という考え。

ストック型ドキュメント

実現すべきことはコードの変更とドキュメントの更新が同期されることである。

これを実現するためには、

などをすれば可能そうである。できるだけ機械にやらせることで人間のコストも低く抑えられる。

なお、CI で落とすタイプのドキュメントは数が多くなりすぎないように注意する。いくら CI でチェックできようが最終的に直すのは人間である。CI で何度も落とされるとモチベも下がるし、ドキュメントの数が増えると人間のコストがどんどん増えていく。

考えていること

正直なところ、「俺の考える最強のドキュメント管理ツール」が世の中に存在していないように感じる。そのため、HOW の部分はあまりしっくり来ていない。 上手いこと最新の状態が更新し続けられる仕組みが欲しいが、既存のツールにはそういった機能がないものが多い、、、

ストック型に関しては、必要以上に頑張らずにプロダクトのコアな部分だけをストック型でメンテし続けるようにし、それ以外はフロー型として整理してしまい、更新を諦めるほうが長く運用を続けるには良いかもしれない。

フロー型は「とりあえずリンクを貼れ」の一言に尽きる。

まだ検討が足りていないところ

ドキュメント管理ツール

git はブランチとマージを使うことでフロー型とストック型を同時に扱える素晴らしいツールである。一方で、よく使われるドキュメントサービスはこのような仕組みを用意していることが少ない。ブランチとマージができるドキュメントサービスを使うことで、フロー型のドキュメントからストック型のドキュメントを生成するといったことができるようになり、より運用を楽にできるのではないかと考えている。

人間がストック型のドキュメントを更新する場合は、差分のレビューが完了するまでドキュメントを更新したくないが、それをしようとすると別の差分を表すドキュメントを作成することになる。 結果としてストック型のドキュメントを作っているはずが、フロー型のドキュメントを作ることになってしまう。 更に、フロー型のドキュメントを作っただけで満足してしまい、レビューが終わってもストック型ドキュメントが更新されないことも多い。わざわざ 2 つドキュメントを作るのはしんどい。

また、たとえこのようなツールが存在したとしても、git とドキュメント管理サービスの同期が取れてないと不整合が起こる可能性もある。 ドキュメントは git でコードと一緒に管理するのが一番幸せなのかもしれない。

何をストック型ドキュメントとして書くべきか

WHY の部分で例を上げてみたが、これらを全て書くべきかどうか、他にも書くべきものがないかどうかがわからない。

書くドキュメントが増えれば増えるほど、コストがかかる。かといって書く量が少なすぎればドキュメントとして役に立たない。この塩梅をどうすべきか難しい。

仕様変更が積み重なった複雑な仕様はどう整理すべきか

仕様変更のたびにフロー型のドキュメントを作成している場合、それらを追えば最新の仕様は分かるが、それを追うコストはとても高い。

こうなってしまった仕様はどのタイミングでストック型のドキュメントは作るべきなのだろうか。もしくは作らないべきなのだろうか

← EnumやUnionの列挙子が増えたときに起こりうる人為的なバグを撲滅したい二項演算子のASTを参考にした動的なフィルターのデータ構造 →
Topへ戻る