メンテしづらいドキュメントを減らすための取り組み

みなさん、こんにちは！株式会社JMDC プロダクト開発部通知開発グループの西川(@wazu_3)です。
普段は健康保険組合向けの個人通知サービスの開発を担当しています。

今年、JMDCではアドベントカレンダーに参加しています。

qiita.com

本記事は、JMDC Advent Calendar 2023 1日目の記事です。
この後も記事をどんどん出す予定なので、チェックのほどよろしくお願いいたします！

早速ですが、本日は「メンテしづらいドキュメントを減らすための取り組み」についてご紹介します！サクッと読めますので、ぜひ最後まで読んでいただけると嬉しいです！

はじめに
この記事の想定読者
メンテしづらいドキュメントって
- ターゲットがブレブレ
- 一時or恒久の判断がつかない
メンテしやすいドキュメントにするために
まとめ

はじめに

まず、ここでいうドキュメントとは

要件定義書
外部・内部設計書
開発環境構築の手順書

など、様々です。

これらドキュメントのメンテをする際に、「これ本当に必要なのかな」「最新化する必要あるのかな」「情報の粒度をどれくらいにすればいいのか分からない。元の情報からも読み取れない...」など、「メンテしづらいな」と感じる瞬間はないでしょうか？
こういった瞬間が生じてしまう原因は、そのドキュメントの 目的がはっきりしていない からではないかと考えています。

実際に私が過去遭遇したケースをもとに、ドキュメントの目的を明確化するための個人・チームでの取り組みを紹介していきたいと思います！

この記事の想定読者

ドキュメントのメンテで悶々とした人・したくない人・させたくない人

メンテしづらいドキュメントって

メンテしづらいなと感じるものは、一体どういうものでしょうか？たくさんあるとは思うのですが、私が実際に感じたものを挙げていきます！

ターゲットがブレブレ

何のために書いたものなのか分からなくなっているドキュメントです。
誰が読むか分からないので、情報の粒度をどこまで詰めるべきなのか、具体性の度合いなどを決めるのが難しいです。捨てたくなってしまいます。とはいえ、参照されている以上、捨てるわけにはいかないものが多いような気がします。

実際に遭遇したものは、社内システムのセットアップ手順書です。
当初のターゲットは、開発チーム内部のみが想定されていたのだと思います。しかし、ある時、システムのユーザー部署からセットアップ手順を要求された際に「このドキュメントをそのまま回せばいいんじゃないか」と共有してしまい、「ここが分かりづらいので情報を補足してくれないか」のようなユーザーからの要求を反映していくうちに、当初の想定とは違うドキュメントが完成してしまったのではないかと推測しています。

一時or恒久の判断がつかない

一時的なものなのか、恒久的なものなのか判断がつかないドキュメントです。

どちらか判断がつかないので、メンテしていくべきなのかどうかの議論が発生してしまいます。網羅性が高いので、メンテしても良さそうなドキュメントも、スナップショットのような位置付けで作成されたものだったりします。

メンテしやすいドキュメントにするために

上記の課題感を解消するために、目的を明確化する改善策を紹介します！

ターゲットをドキュメントに書いてしまう

シンプルです。ドキュメントの冒頭に「本運用マニュアルは～に関する操作を解説します。」など具体的に記載してみます。限定的であることを明示することによって、参照する人はもちろんのこと、メンテする人が「あ、ユーザー向けのドキュメントなら、情報をある程度噛み砕く必要があるな。」「このドキュメントはユーザー向けなので、開発内部向けのものは別途作成しよう。」と判断することができます。

チーム内で一時or恒久を決める観点をすり合わせる

チーム内で、一時or恒久の基準をすり合わせるブレストを実施しました。
ドキュメントを恒久的（維持していく）とするかどうかは、様々な観点でのトレードオフであることがほとんどです。
これらの観点をすりあわせることによって、作成する際にはもちろん、メンテする際にも「保守コストが高いのに、参照する機会は少なそうだから、リターンが小さそうだ。チームとして、これは維持しなくてもいいドキュメントだな。」と判断することができます。

一時的なドキュメントを格納する場所を設ける

tempであることを明示します。「work」ディレクトリを作成して、一時的なドキュメントは、はじめから、「work」ディレクトリ配下に置くようにしています。
そうすることで、将来的に発見しても「これはtempだから最新化する必要はないな。恒久的なものは別途作成しよう。」と判断することができます。