筆者の様な、社内業務システムの開発者にとっては悩みの種である、開発システムのドキュメント整備。
SES等の委託系のシステム開発方法と違い、
- 同じオフィスでシステムユーザーと直接やり取りできる影響で、厳密な仕様書を書かず口頭で仕様を決める事が良くある
- 小規模システムだと設計者と開発者が同じ人になる事が多々あり、設計書が頭の中にあっても問題ない
- 保守業務も開発者が流れでやる事が多く、不在時に他のメンバーが対応できない
といったように、キチンとした部署でない限り、こういった業務改善系のシステム開発は必要なプロセスがなぁなぁで済まされる事があります。
我が部署もそのような状態であったのですが、対象システムの量と規模感的に大規模サービスレベルのドキュメント類を整備するのは正直オーバーワークでした。
そのため、コスパよくドキュメント整備と引継ぎを行うにはどのようにすればいいのか、検討して理論化してみたというだけの記事です。
Qiitaではあまり見かけない業務改善系のエンジニアに向けた記事で、
あまり参考にならない記事だとは思いますがメモ書きとして残しておきます。
引き継ぎ項目
- 概要説明。システムが使われている業務の概要、システムの立ち位置・目的を知る
- 業務フロー(システム内部仕様は除く)
- システムの実物を見せながら、使い方・正しい挙動を説明
- システム設計の概要説明。(仕様技術やアーキテクチャ、ざっくりとした仕組み説明)
- 業務フローを再び追いながら、システム内部仕様を説明
- UML、ER図等の細かい仕様書を各自でインプットしてもらう
- システムの不具合が起こりやすい部分や、過去に頻発した問題、対策方法等の説明
基本的にこの順序通りに進めると理解しやすい。
また、これらは資料＋実際の説明中の録画データとして残っていると一番良い。
筆者の部署は、Teamsで説明し、録画データを無期限保存する事で対応
解説
6番はよくある「設計書」として用意される資料だが、これだけ作っていてもシステムの実際の使い方が良く分かっていない状態であるため、理解するのにかなりの労力がいる。
また、ユーザーからの「この機能を使っていたらエラーが出た」と言うような連絡について、システムの詳細設計だけを知っていても実際の使い方との紐づけが出来ていない状態なので、どうすればいいか分からない。
１番のみを行っていた場合も同様で、実際の使い方との紐づけが出来ておらず対応できない。
業務アプリ等であれば、最低限業務フロー図は作らなければいけないだろう。
どこまで用意すればいいか？
■マクロ(データ加工系)
ExcelシートをDBにINSERTするだけのマクロや、シートを加工するだけのマクロ、ＤＢから少しデータを持ってくるだけのマクロであれば、システムの概要説明を数行でするだけで役割が理解できる。前後の業務フローを理解していなくても、インプットイメージとアウトプットイメージさえ分かっていれば問題ない。
後は中身を見るだけで、基本的な技術者であれば改修が可能と思われる。
引き継ぎ項目1と3を行う。
■RPA
概要説明を行い、業務フローを説明する事で、システム仕様を説明したのと基本的に同義になる。バックグラウンドでのDB処理等、業務フローに書かれない所だけを追記すればよい。
引き継ぎ項目1と2、余裕があれば自動化前の画面で3を行う。
■マクロ(システム系)、Access
複数のマクロを組み合わせたExcelシステムの場合、ほぼアプリと同義であるため、
概要資料、業務フロー、使い方だけでなく、実際にこのマクロを起動するとどのような処理が行われるのかを順を追って説明する必要があると思われる。
Accessについても同じ。
引き継ぎ項目1,2,3,4,5を行う。
6のUML等に関しては、マクロやAccessだと表現するのに適さない場合もあるので、これは任意。
■アプリ
アプリに関しては、内部構造が複雑であることが殆どなので、基本的に引き継ぎ項目1~6全て用意するのが望ましい。業務での使用目的、業務の中でどう使われるのか、業務で使ってる機能の内部構造の概要等は割と知っておかないと保守が難しいレベル。
休暇対応
連休等で居なくなる場合は、全てを行うのは時間的に足りない場面が殆どであるため、トラブル頻度、トラブル時のリスクの大きさを考慮して引き継ぎ範囲を限定するのが望ましい。また、引継ぎ内容は、基本的に業務停止につながる重大なトラブル事例と、その対処法について教える事に重きを置く。