Zenn
😇

後任・新規着任者を泣かさないためのバックエンド開発者向けドキュメント管理について

2024/03/31に公開
#
仕様書
#
ドキュメント
idea

本記事に書いてあること

ちゃんと作成または更新しておいてほしいドキュメントを整理し、更新をサボらないようにするための仕組みについて軽くまとめます。

なぜドキュメントを作成 & 更新してほしいのか

実際に動いている環境やコードを見に行けば、ドキュメントが無かったとしても一応の運用・機能追加/改修は可能です。

しかしながら、 なぜこの実装になっているのか（Why）が読み取れない 、そもそも どういう実装になっているか（How）を把握しづらい といった問題が生じます。それは非常に辛いことであり、後任の方が泣いてしまうこと必至です。

後任を泣かせずに済ますためにも、以下の２つのポイントを守ったドキュメント作成が求められます。

  1. コードから読み取れない情報を無くす・減らす
  2. 各レイヤーで全体の概要がわかる

作成 & 更新しておいてほしいドキュメント

プロジェクト全体や現存機能の概要については、流石に誰か1人は把握しているので聞けばよいだけですが、それよりも低いレイヤーを把握していないことは往々にして発生することでしょう。
バックエンド開発において、それらのレイヤーを把握するドキュメントとしては、以下のドキュメントがあります。

  • レポジトリ・コードベースについて
  • REST API や GraphQLのAPI仕様書
  • ER図
  • アーキ図

以下詳細です。

レポジトリ・コードベースについて

実際に触ることになるコードおよびその動作環境 についての情報ですね。
大きくは 少なくとも今のコードが動くことの保証 と コードの中身を追いやすくする という２つの目的を達成するために書いておきます。
README.md や CONTRIBUTING.md に書きましょう。
具体的には、ディレクトリ構成とその説明のほか、開発環境の構築、テストの実行方法など各種開発用コマンド等について記載しておけば良さそうです。

REST API や GraphQLのAPI仕様書

機能概要の一段下のレイヤーの各機能に関する情報であり、具体的にはどんな機能があり、それぞれ何を渡せば何が返ってくるかということを知ることができます。機能詳細の中のトップレイヤーの情報 と言っても良いかなと思います。

RESTであれば swagger.yaml, GraphQLであれば schema.graphql といったファイルを管理することになるかなと。
入出力の項目名と型くらいはわかっても、それぞれが何を表しているのかわからない、ということはあるので、そのあたりの説明も可能な限り含めましょう。具体的な値・例もあると親切です。

これらをHTMLやMarkdownにするなりできるライブラリは色々あるので、これらのファイルの管理さえちゃんとしてれば可視化してわかりやすく見ることは容易です。

そこに書ききれない事項があれば別途記載することも必要です。

ER図・テーブル定義書

入出力の情報がわかったとしても、実際に処理を書くためには、どのようなデータがどんな形式で存在するのかを把握しなければコードは書けないため 当然これも必須ですね。

Draw.io などを使用し、SVG形式で管理しておくと、GitHub上での差分も見れて便利です。
リレーションシップがわかったとしても、各項目の意味するところがわからないとカラム名から推測するしかなくなるため、テーブル定義書も合わせてほしいところです。

アーキ図

特にサーバレスアーキテクチャでは、複数のサービスが絡むことになるため絶対にほしいところです。
また、全体のアーキ図の他に、各APIで副作用がある場合についての個別のアーキ図もあるとかなり親切で助かります（メールの配信が実行される、バッチ処理・非同期処理が走る等）。

その他できればほしい

  • テスト計画・実施結果: 具体的な仕様の把握に役立つためほしい
  • （思いつかないが他にもありそう）

ドキュメント更新をサボらないための仕組み

作成されていたとしても、最新のものに更新されていなければ意味がありません。そこでそれぞれ可能な限り頑張らない工夫がいくつかは存在します。

レポジトリ・コードベースについて

DevContainerを使いましょう。それにより開発環境構築が容易になるほか、開発者間の差分を0に近づけることができます
ディレクトリ構成等の説明については、__FOLDER_OVERVIEW__ とか README.mdを各ディレクトリに配置すれば自動でいい感じにツリー上の説明資料を作るツールとかほしいところですが、私は把握してません。自作するしかないかも。

REST API や GraphQLのAPI仕様書

yamlファイルは更新されなくなりがちなので、できればコードから自動生成することを考えるのが良いかと。
FastAPIではデフォルトで生成してくれるようですし、NestJSにも生成機能があります。

ER図・テーブル定義書

こちらも自動生成するツールがあるようなので、できればそれを使いましょう。
ただし、全体のER図を無機質にただ出力しただけでは、正直見づらくて使い物になりません。

Prismaを使用している場合は、 prisma-markdown が良さそうです。
利用については今絶賛検討中ですが、 @namespaceを schema.prisma の各テーブルのコメントに追加することで、 機能別で関連するテーブルのリレーションシップのみを表示させる といったことができるそうです。（リンク先のデモを見るとわかりやすい）
また、同様にコメント機能を利用して、markdown形式で各カラムの説明もまとめることができるのも良さそうですね。

アーキ図

図の前に、とりあえず IaaCでコード化しておきましょう。少なくとも何のリソースが存在するのかだけでもそこから把握できるはずです。
terraformであればいくつか可視化ツールがあるみたいなので、それも利用するとより把握しやすいと思われます。

とはいえ、アプリレベルでどれが何を呼び出しているかは、基本は手で更新するしかないのかなと。ここだけはちょっと気合で頑張っておくしか無さそうです。

結論

このようなドキュメントが最新化されている & 更新する仕組みも整っていると後任・新規着任者の方も安心して仕事できますね！

余談

今泣いてる 😇

Discussion