弊社では各種ドキュメント(ルール、手順書、仕様書に至るまで)を基本的には Notion で管理しています。ドキュメントを作成、共有する方法として非常に手軽で便利ではあるのですが、多くは個人の裁量に委ねられており、以下の点で課題を感じています。
- 信頼性: 古くなった情報や間違った情報があったり、またその判断がつきづらい
- 情報不足: 過去との差分など断片的な情報だけで、背景を知らないと理解できない
- 検索性: 構造的に整理されておらず、検索頼りで必要な情報を見つけづらい
要因としては以下のようなものが考えられるかと思います。
- 意図や背景が分からず、修正すべきものか判断できない
- 誰に確認するのが適切か分からない、面倒 (責任の不在)
- 逆に手軽すぎて間違ったものが入り込んだり、放置されがち
このような状況では、作業が非効率になったり、間違った情報から品質への影響も危惧されるほか、メンバーのストレスにもつながります。より良いドキュメントを運用するために、これらの課題を解決する方法を模索中です。
ドキュメントの分類を考える
一口にドキュメントといっても、それぞれ用途は異なるため、特性によって管理方法は考えたほうが良さそうです。以下のものは明確に分けられそうです。
ログ/イベント: ある時点での提案や意思決定などの記録
- 議事録、設計・検討メモ、提案書など
- 主に短期的に使用するが、必要に応じて見返す場合がある
- 当時の経緯や思考を残す目的があるため、不要になった内容も削除しない
ストック: 常に変化する最新の情報
- 仕様書、設計書、手順書、ルール、技術的な HOWTO など
- 長期的に使用され、最新の情報だけが維持されている必要がある
- 古い内容(変更履歴)は必要に応じて取り出せればよい
- 柔軟に書き換えることができることが望ましい
「ログ/イベント」に分類されるドキュメントはとにかく記録されていることが大事であり、気軽に作成できる Notion のようなツールのほうが良さそうです。主にここで「ストック」に分類したドキュメントが信頼できるものであり続けるための仕組みが必要になると考えます。
GitHub によるドキュメント管理を考える
エンジニアなら Markdown や Git は日常的に使っており、より汎用的なものを使用することで持続可能という観点でも有効なのではと思いました。以下のような利点が考えられます。
- PR による承認、共有フロー (レビュー記録も残る)
- PR によるコメントや修正提案 (レビュー記録も残る)
- 変更履歴を追いやすい
- Mermaid 形式で図を記述すれば GitHub 上で自動で表示できる
- 編集可能な画像を埋め込み、ローカルで編集できる (draw.io など)
- ローカルですべてのドキュメントにアクセスできるため、各々お好みのツールで検索、編集できる
余談ですが、外資就活ドットコムで提供しているコラム記事の管理も従来使っていた CMS から GitHub を使用した仕組みに切り替えようとしています。エンジニア以外のメンバーも GitHub を使えるようにしようというチャレンジでもあります。
リンク切れ対策を考える
ドキュメントというものはしばしば別のコンテキストからの URL で参照されますが、GitHub で管理した場合、ファイルパスがそのまま URL に紐付くため、ファイル構成の変更をおこなうとリンク切れになってしまうため気軽に移動できません(Notion だとページ毎に ID が振られ移動しても変わることがないのは良いですね)。ファイル構成はドキュメントの成長とともに変更したいことはよくありますし、ドキュメントを追加するときの心理的負担もあがります。対策として以下のような案を考えました。
案1. ドキュメントのファイル配置をフラットにする
各ドキュメントファイル自体はすべて同じディレクトリ配下に置き、ドキュメントの階層構成は目次としてのページを作りドキュメント内で表現します。ファイル名は変更しないルールとするため、UUID などを生成する形にします。
この場合、ドキュメントが増えてくると編集するときに探すのが大変になりそうです。
案2. サイト生成ツールを使用する
Jekyll や Docusaurus といったドキュメントサイトをビルドするツールを使用すると、各ドキュメントファイル内にメタデータとしてパスを記述することで、URL を固定化することができます。ドキュメントの参照は GitHub 上ではなく別のサイトで公開する形になります。
サイト上の URL と GitHub 上のファイルの対応が分からなくなり編集時に困るかもしれないと思いましたが、生成されたサイト内から GitHub 上のパスに飛ぶリンクを自動的に付与する機能もあり、大きな問題はなさそうです。
また以下のような利点も考えられます。
- ディレクトリ構造から目次を自動生成する機能を使えば、ドキュメントの論理構造に合わせたファイル配置にすることで、目次用のページを作る必要もなくなりそう。
- ツールのチェック機能で、ドキュメント間のリンク切れも検出してくれる。
- PlantUML や Mermaid などプラグインを使うことで、Markdown に埋め込むことができるフォーマットを拡張することできる。
ツールに依存しないという方向からは少し外れてしまいますが、わずかな独自記述を追加するだけで対応はできるため、使い過ぎなければ大きな問題はないかなと思います。
ドキュメントサイト生成の自動化
GitHub からツールを使ってドキュメントサイトを生成するには、GitHub Pages を使うのが手軽ですが、公開範囲を限定するには GitHub Enterprise プランの契約が必要になり、閲覧者にも GitHub アカウントが必要になります。
以下で紹介したサイトを社員向けに限定公開する仕組みを使って、GitHub Actions でビルドして S3 にアップロードする形にしてみました。
全体像はこんな感じです。
さいごに
みたいなことを考えている段階ですが、思いついた仕組みを整備しながら、一部のチーム内でお試ししてみています。良かったら横展開していきたいと思っています。
ドキュメントに限らず、どのツールやシステムを使うにせよ、その優劣よりも、目的・方針のもとメンバーがそれを理解して運用するということのほうが肝要だということは忘れないようにしたいと思います。
