ぺやろぐ

ぺやろぐ

焼きそばよりチャーハンが好き。

保守開発におけるドキュメントの大事さを知った

スポンサーリンク

f:id:peyangu485:20200628135307p:plain

お腹のお肉が気になり始めました。
ぺやんぐ(@peyangu485)です。

早いことで転職して3ヶ月経った。
そのことに関しては別の機会にするとして……。

この3ヶ月で資料を残すことは大事だなと実感を持って知れた。
少し前までは「ソースコードを見れば分かる」、「コミットログを見れば分かる」、「設計書があるんだから大丈夫」と考えていた。
だが、それらは恵まれた環境の話だということを思い知った。

今日は、そう思い至った経緯を書いていく。

資料が残っていない案件

この4月から参画している機能追加案件で対象システムの設計書等の管理がなかなか酷いものだった。
初期開発がすでに大炎上で、整える時間がなかったんだろうとは思うが、そのあとの改修時にちょっとは手を入れてるのかと思いきや、思いっきり属人化が進んでいた。

どこに何があるのか、資料は正しい内容なのかが不明、引き継ぎもなし。
頼れるのはソースコードのみだけど、それはそれで悲惨な中身。

メンバーに有識者がいるわけでもない。

4末で終了するという当初の話はなんだったのか、現在でもまだ終わっていない。
主な理由はコロナなんだけど、他社のシステムとの連携テストや連携時に発覚した不具合などの修正待ちなどでズルズルと延びている。
結局、現地リリースは1ヶ月遅れ、本格稼働はさらに半月以上後になった。

コロナによる延期で吸収できたが、引き継ぎ不足による仕様の誤認が多発した。延びてなかったらと思うとゾッとする……。
さらに現地リリース時には、資料にはなかった設定が出てきたり、現地の設定ファイルと開発環境で残っていた設定ファイルの中身が違うなどの問題が起きた。
現地のPCにしかない資料があったり……。

作らんといかん!!

ということがあって、何としても時間を作って資料を作らなければならないと決意した。
次、自分がやるとしても必要だし、このシステム未経験の人が触る可能性もあるし。
そして、今回残す資料は他のシステムでもデフォルトで作成する必要があると思うから、しれっと標準化できるようにしておく。

形式としては、図表を使わないものに関してはテキストベースで管理できるMarkdownで作って、図表がいるものはExcelで作るようにした。
選定理由としては、

  • 開くExcelの量を減らせる
  • 大量の文章を書くのにExcelは向いていない(めんどくさい)
  • 変更比較できるようになる
  • ただのテキストよりは修飾しやすい

といった点で、選んだ。
あくまで今の段階での話だけどね。
結局、Excelで統一した方がいいってなるかもしれないし、Excel完全撤廃を掲げるかもしれない。

作る資料としては、

  • 用語集
  • ソースコード・モジュール管理について
  • 参画時にすることリスト
  • ドキュメント整備について
  • リリース手順
  • ローカル開発環境構築手順
  • 稼働環境構成

これらは、この記事を参考にして作ることを決めた。

taityo-diary.hatenablog.jp

これで、とりあえず運用してみよう。
あかんかったら、新しいのに合わせて作り直さないといけないけどね……。

さらに、フォルダ構成も微妙だったので見直しを行っている。
とりあえず、雑なくくりだったのを少し厳密にしてみたり、開発の最初に読む資料をまとめたり、ツールフォルダが案件ごとに作られていたので、共通フォルダに置いて無駄なコピペをしないようにした。
同じツールが2,3個コピーされているのを見た時はげんなりした。

で、ある程度基本形ができたのでPowerShellで「自動でフォルダを作成する」バッチ(でいいのか?)を作って、次からは実行するだけで作成するようにした。

まとめ

これで少しは次の機能追加時に導入が楽になるといいなぁと思う。
同じような思いは、今後させてはいけないと思うし。

ありがたいことに、これを浸透させることができる立場だし、どんどん標準化させていこう。