はじめに

はじめまして！
BASEのカートチームでバックエンドエンジニアをしている @ykagano です！

カートチームは主にBASEのショッピングカート機能の開発を担当しているチームです。
そんなカートチームでのドキュメント管理術をご紹介したいと思います！

ドキュメント管理の課題

BASEではNotionを社内Wikiとして使用しています！
社内資料は、Notionのページやデータベースで一元管理しています！

カートチームでもドキュメントはNotionの一つの階層構造で管理していますが、使用している中で以下の課題がありました。

大抵のページは最初に書かれた後、ページが更新されない
- ページ作成者以外は更新しづらい心理的な壁がありそう
毎回新しくページを作っているため、新しい情報と古い情報が混在している
- 古いページに前提となる情報が書いてあることも

課題を解決するために

Notion AIを使用しています！
AIに尋ねれば各ページの情報を元に情報が出てくるのですごく便利です！

でも正しい情報が一発で出てくるとは限りません。
鮮度が古い情報を拾ってくることもあります。
毎回同じことをAIに尋ねていることも……。

そこで、よく使う情報はチームの共有ページにまとめておくことをお勧めします。
これにより、以下の利点があります。

必要な情報にすぐにアクセスできます
チームメンバー全員が同じ情報を共有できます
チーム全体の開発効率が向上します

さらに、まとめたページは、Notion AIと組み合わせることで、より効率的に情報が検索できるようになります。

カートチームのドキュメント管理

ではNotionを使った具体的な管理方法を見ていきます！

カートチームでは一つのNotionデータベースにナレッジを集約しています！

cart-team-notion-database

ただ更新されないままになっているページも多いです。
時間が経つとページも増えてくるので、全てのページを最新化するのも困難な状況です。

そのため、カートチームでは、ポータルページで保守するドキュメントと保守しないドキュメントを分けることにしました。

カートチームのポータルページ

下図はカートチームのポータルページのトップです！

最初に保守対象のページを表示してすぐアクセスできるようにまとめています。
保守対象のページはチームメンバー全員で更新していくページとなります。

cart-team-portal-page

先ほどのデータベースの中から以下のラベルの付いたページを保守対象としてビューに表示しています。

チーム運営
保守（運用）
保守（技術）
保守（メンテナンス）

次に保守対象外のページです。

cart-team-portal-page2

左側はデータベースの一覧に新規追加された資料を表示しています。
右側は保守対象外のラベルで資料にアクセスできるようにしています。

最初は工事中のページも資料が育てば、ラベルを付けて保守対象にしています。

資料はチーム全員で育てるものです！

その時気になったことが一行だけ書かれたページでも、後から気付きを得て、書いた方がいいと思ったことはどんどん追記しています！

カートチームはBASEの決済動線を守るチーム

これまでは主に業務視点のドキュメント管理術でした。

カートチームはBASEの決済動線を守るチームです！
そのメインの仕様書はどうやって管理しているのかをお話ししたいと思います！

仕様書を常にメンテナンスすることは非常に困難です。
案件ごとにNotionやFigJamを使って資料は作っていますが、保守対象としている仕様書は一つに絞っています。

それはシーケンス図です。

決済手段ごとに外部連携先（主に決済会社）も異なれば、非同期処理になっている箇所もあります。
監視ではどこが障害ポイントになるのか確認し、改修時はどこを変更することになるのか検討が必要になります。

そうした時に素早く共通認識が持てるように、処理全体が俯瞰できるシーケンス図を更新しています。

シーケンス図をGitHubで管理する

シーケンスを以下のようにGItHubで管理しています（表示部分は一部です）。

cart-team-sequence

GitHubはMermaid形式のプレビューに対応していますので、Mermaid形式で書いたmdファイルを格納しています。

カートチームの決済動線のシーケンスは主に以下の階層構造になっています（あくまでイメージのため、一般的な概念図まで簡略化しています）。

sequenceDiagram
    participant User as ユーザー
    participant Front as フロントエンド
    participant Back as バックエンド
    participant Payment as 決済会社

    User->>Front: 商品選択・購入ボタン押下
    Front->>Back: 購入リクエスト送信
    Back->>Back: 在庫確認
    Back->>Payment: 決済実行
    Payment->>Back: 決済結果通知
    Back->>Back: 注文情報保存
    Back-->>Front: 決済完了通知
    Front-->>User: 完了画面表示

シーケンス図はバックエンドのGitHubリポジトリに格納しています。
決済動線の処理が変更になるときは必ずバックエンドが更新されるためです。

決済の処理フローに変更が発生した場合、コード修正と合わせて、シーケンス図も修正するようにしています。