Edited at

システムのドキュメント整理と新メンバー加入時の説明順序

More than 1 year has passed since last update.


この文書について

構築済のシステムについて、保守の引継ぎや追加開発時の増員があったとき、

「新しく参画したメンバーがすぐにシステムを把握するために、どうしたらよいか?」

を考えた際のメモ


背景


問題

新しいメンバーの習熟に時間がかかる


原因


  • ドキュメントがない・整備されていない


    • 初期構築に関わった人が運用をそのまま実施しており、ドキュメントがなくても困らなかった


      • 新しく人が入ってきて、ようやく気づく



    • 索引がなく、知りたい情報がどこにあるか探すのが大変

    • 今、何が正しいかがすぐにわからない


      • 初期構築時の要件定義書はあるが、追加開発で要件が変わってしまった


        • 追加開発時のドキュメントも全部読まないと何が正しいかがわからない







  • 說明が体系だっていない


    • OJT的な教え方しかできていない


      • 運用や小規模改修から入って、徐々に慣れていってもらうはずが、
        枝葉の部分だけ詳しくなってシステムの全容はわからずじまい






是正案

以下を実施する


  • ドキュメントの整備

  • 說明の構造化

  • 改善を回す


ドキュメントの整備

最低限、以下のドキュメントが必要


  • 機能要件 (用語定義も兼ねる)

  • 基本設計・インフラ構成図

  • ストレージ設計 (ER図など)


ドキュメントリポジトリの構造

例えば以下のような構造

- README.md        システム概要の說明

- glossary.md 用語集
- design/
- README.md 基本設計
- infra/
- InfraDiagram.png インフラ構成図
- InfraDiagram.xml pngの元になったdraw.ioのファイル
- storage/
- ErDiagram.mwb ER図 (MySQL Workbenchのファイル)
- FileFormat.ppt 外部連携システムのベンダから貰った連携ファイル仕様など
- api/swagger.yaml API仕様 (SwaggerUIに食わせるyaml)
- batch/README.md バッチ一覧、バッチごとの役割說明

詳細な說明については各ソースリポジトリのREADME.mdなどに書く。


說明の構造化

要件 -> 基本設計 -> 詳細設計 の順に説明する。


  • 機能要件を説明する


    • 何のためのシステムなのか

    • 誰が使うのか

    • 固有の用語があれば、この段階で意味を說明しておく



  • 基本設計・インフラ構成を説明する


    • 要件を満たすためにどうアプローチしたのか

    • サブシステム分割したのであれば、データの流れと各サブシステムの役割を説明する


      • 例)


        • 外部から連携されたファイルをバッチがDBに取り込む

        • CMSで運用担当者がDBのデータを追加・変更する

        • APIでデータを利用者に提供する







  • ストレージ設計を説明する


    • RDBであれば、テーブル定義とその役割を說明

    • ファイル出力系があれば、別途補足する


      • バッチアプリケーションで外部連携する場合に顕著





  • 各アプリケーションの說明


    • APIであれば、エンドポイントのSwaggerなどを見せた上で、
      リクエスト、レスポンス、ストレージへの副作用を說明

    • バッチであれば、起動引数、標準入出力、ストレージへの副作用などを說明



↑の内容を説明したら、ソース取得・ローカル開発環境構築・結合テスト環境デプロイなど、

改修の実作業に移ってもらう。


改善を回す

ドキュメント化・說明の構造化は始めたばかりなので、最初に作ったものが完全ではない。

また、説明する側(Trainer)自身のソフトスキルも磨き続ける必要がある。

このため、以下のフィードバックサイクルを回す。


  • Trainerは新しく入ってきた人(Trainee)に說明する

  • Traineeの理解・定着度を測る


    • 改修におけるタスク着手前に
      Traineeがシステムについての理解をTrainerに説明する



  • もし理解が間違っていた場合、何がわかりにくいかをTraineeに尋ね、改善方法を検討する