こんにちは、タロウです。

開発を進めるにあたり避けられない画面設計書などのドキュメントですが、
管理をNotionへ移行しメンテナンスしやすくなったのでご紹介します！

ドキュメントのよくある失敗

• 開発が長期になればなるほどメンテナンスされなくなる（ソースが全てだ！の精神）
• 書く人によって書き味が変わってしまう
• ドキュメントが散らばっていてどこに何があるのかわからなくなる

もちろん綺麗に管理されているプロジェクトも多くあると思いますが、
僕は割と散らばっているプロジェクトで多くを過ごしてきました。

こんな人、プロジェクトにおすすめ

• ドキュメントの形式制限に融通が効く（納品時のドキュメント形式に制限が無い）
• 上流から方法を変えていける or 決めていける環境にいる
• とにかくツールを1つにまとめたい

ドキュメントに使用しているツールが散らばるだけでもう煩雑に感じてしまいます。

画面設計書の例

簡易的な例ですが、実運用している形式を紹介します。

画面設計

画面について知りたい場合はここへアクセスするだけで
シンプルに全貌が見え、各画面の設計書へアクセスできるのみとしています。

画面設計のTOPには、画面遷移図や画面一覧を乗せています。
プロジェクトによってはURLやアクセス権限などを載せても良いかもしれません！

画面詳細

各画面の設計書です。
読む側が混乱しないよう何ができる画面なのかを第一に記載しています。

ごちゃっと書きたいことところを下記フォーマットで揃えることで
全画面通してシンプルにわかりやすくしています。

• この画面では何ができるのか
• どんな画面なのか
• 各コンテンツの表現方法や入力制限など
• API連携の有無、関連するAPIの情報
• 権限制御
• その他

また、見出しや表などを簡単に取り入れること、
追加もページのコピーも簡単に行うことができるので、
画面が増えた際の使い回しもとても楽になりました。

ER図の例

テーブルの情報、リレーションシップがわかるように図でも表現しています。

このようなイメージでテーブルの一覧、ER図はMermaid記法で記述しています。
テーブルやカラムの増減もメンテナンスがしやすく、
また、関係性も自動で繋いでくれるので自分で線を引く必要がないのもとても良いです！

Mermaid記法のイメージ

プレビューを見ながら書くことができる分割モードもあるので
不自由なく書くことができました！

もっと工夫できそうな点

表形式で表現するドキュメントに関してはある程度テンプレート化できそうなので、
効率よく活用することができそうでしたが、
その反面、もっと工夫すればスマートにできそうな点が見えてきました。

• 画面ID(採番)を一箇所で管理するために、テーブルから各画面詳細へのリンクを貼ると良さそう
• 各画面詳細のIN/OUTや入力制御などは、別の表へ切り出すと見やすそう
• 別ツールで作成した画面イメージをスムーズにNotionへ連携できれば良さそう

タイトルや画面名が変わる度にいろんな部分を直さなければいけないなど、
メンテナンス性の悪さに直結する課題は序盤で解消しておくべきだと感じました。

さいごに

今ある膨大なドキュメントをNotionに完全移行するのは現実的ではないかもしれませんが、
スモールスタートのプロジェクトや、個人開発などから
導入して運用するメリットは多くあると思います！

カスタマイズを繰り返してより良く管理できるよう模索してみたいと思います！