Notionで安心・快適な仕様ドキュメント作成ライフを送ろう
きっかけ
JDSCプロダクトマネージャーの小山内 (@koyamauchi)です。
弊社では常に同時並行で複数のプロジェクトが進行しており、社内のエンジニアチームとPdMがワイワイがやがや コミュニケーションを取りながら、日々サービス開発に勤しんでおります。
私がメインで担当しているWodom!の開発では、スクラム開発の体制を取っています。(JDSCって、自社で開発してるの?? っと聞かれる事も多いのですが、バリバリやってます！！詳細は、また別記事にて紹介予定)
開発着手時点で全ての仕様を定義するのは不可能な為、初期的な仕様ドキュメントを最初に1通り用意し、実際の開発タイムラインに乗ったタイミングで、要件を精緻化する形式を取る事が多いです。
現在、大きな新機能の開発を控えているフェイズとなっており、改めて仕様ドキュメント記述に用いるツールを検討した結果、Notionが目的に対してFitしそうと感じたため、Notion with 仕様ドキュメント記述という切り口で、活用方法を紹介します。 (既に同じような使い方をされている人がいたら、是非ご連絡ください！)
※ちなみにここで記載するのは、あくまで内部開発者向けの要件定義文書であり、対外的に共有したり、納品物となり得る開発文書を指している訳ではありません。外部クライアントに対しては、主にプロトタイピングツールを用いた動作デモ 及び 足りない場合はppt補足説明資料を使った仕様擦り合わせを実施するようにしています～！
仕様ドキュメント作成が抱える複雑さ
”仕様ドキュメントが残っていない” / “どこに仕様が存在するのか分からない” など、どこの現場/PRJでも、完全無欠の仕様書が存在していて、きちんとワークしているという桃源郷は無いのではないか?と思います。
これには、仕様ドキュメント作成というタスクに、2つの難しさが存在するからだと思っています。
元々JIRAをチケット管理ツールでメイン利用していることもあり、現在はConfluenceで仕様記述を行っており、それを用いたアプローチで仕様ドキュメント作成の難しさに対応してきました。
※Confluenceの詳細な説明は省きますが、元がWikiツールが出自であるので、利用した事の無い方は、Google Wikiや、Wikipediaを想像頂くと、以降の内容も理解しやすいと思います。
難しさ1: 必要な情報がどこに存在するのか?を、執筆者以外が特定するのが難しい
執筆者の中では、構造化されて整理された情報であっても、初めて見る人にとってはどこにどの情報が存在するのか?分からなくなる場合もあります。
特に、チームにジョインしたばかりの開発者がいるような場合は、顕著でしょう。
この点に関しては、プロダクトの1つ1つの仕様を シナリオ > ユーザーストーリー > ビジネスロジックの3層に構造化し、Wikiページでも表現する事で解決を図りました。
例えばTODO管理ツールがあったとしたら以下のように構造化する事で、必要な情報を見つけやすくします。
エピック => TODOリストのCRUD
ユーザーストーリー => タスクを作成する / タスクを更新する / タスクにタグ付けする / タスクを削除する
ビジネスロジック => タスクのステータス一覧詳細 / タスクの画面項目定義 / ユーザーロール毎の実行可能操作一覧
Wikiツールを使う場合は、まず親ページでシナリオを記述して、子ページとして複数のユーザーストーリーを作成します、その子として更にビジネスロジックを記述します。こうした構造を持つことで、1つ1つの仕様の探索性を確保します。
発生した課題
という風に作戦は立てたものの、Wikiツールで上記を実行するには、かなり苦労しました。
まずは、リレーションの陳腐化の問題です。Wikiツールで上記を実現するには、”親ページに関連するページを子ページとしてリンクを貼る” という作業をするのですが、これらのページ間のリレーションを維持するのは、結構大変な作業です。
しかし、新規のプロダクト開発の際には、ストーリー数は比較的小規模なものであっても数十個にもなります。新しいページを追加する度に、毎回リレーションを定義し続けるのは、それなりに負荷のかかる作業となります。
また、シナリオに対してユーザーストーリーを複数紐付けたならば、逆にユーザーストーリーからシナリオを参照できるように、リレーションを定義したくなるのが、人情というものです。(私だけでしょうか?笑)
親ページから、子ページにはリレーションを貼っていて辿れるが、子ページからは辿れず、仕様の理解が難しくなるという場面も、チラホラ発生してしまっていました..mm
難しさ2: 情報を最新にアップデートし続けるのが難しい
また、仕様書は常に最新の状況をアップデートしておかないと、やがては利用者が内容を信頼しなくなり、陳腐化してしまいます。
従って、Slack上でやり取りが発生したら直ぐにWikiツールに仕様反映する事をルール化する / 一覧で情報を閲覧できるページを作って編集しやすくする など、常に最新情報を提供する事は意識していました。
発生した課題
とやってはみたものの、ドキュメントの更新が後手後手に回ってしまう場面もありました。これは、Confluenceのページがコンテンツが一定以上増えると動作が重くなるというのも一因としてあります。
思いついた時にパッと編集して、パッと保存できるというのは、些細なことに思われますがドキュメンテーションツールでは重要な要素であり、更新性に影響を与えます。
また、Wikiツールの特性として、一覧性の低さも課題でした。ページにリンクを貼り付ける事は出来たとしても、中身を確認するにはページをクリックして、詳細に潜らないと行けないので、1hopプラスで作業を要求されます。
こちらも、わざわざページまで見に行けば気付くけど、通常は気付かないような更新箇所の見落としが起きていました。
まとめると、以下のような難しさに対して、WikiツールとNotionでそれぞれアプローチをしています。
いよいよNotionの紹介
やっとNotion出て来た～！という感じですが、基本的なツールの使い方の紹介は他にも良記事が沢山あるので、そちらを参照ください。今回は、以下公式ドキュメントにも記載があるデータベース機能を主に使っています。
Notion — The all-in-one workspace for your notes, tasks, wikis, and databases.
使ってみると分かるのですが、1つ1つのページの記述方法はWikiだろうが、Notionだろうが大して変わらないのですが、データベースを使う事で、データとViewを分離できるのがユニークな点です。そして、この機能こそがNotionの最も優れた部分だと考えています。
これによって、上記で抱えていた課題の大部分を解決できる事が分かりました。
打ち手①: データベース機能を用いてカンタンに3層構造を表現する
データベース機能では、単純に任意の列を定義するだけでは無く、テーブル間のリレーションを定義する事ができます。
メリット: データベースリレーションで情報を構造化する
つまり、情報を構造化でき、JOINを使った情報取得->表示の流れをノーコードで実現できるという事です。というのもあり、私はドキュメンテーションツールというよりは、データベース機能を持ったNoCode開発ツールと捉えた方がより実体を表しているのでは?と考えています。
今回の例では、シナリオ + ユーザーストーリー + ビジネスロジックのテーブルを作って、リレーションを定義していきます。(列タイプに文字通り、Relationという項目が存在します)
これまでは、親ページへのURL貼り付けという極めてアナログな方法で実現していたリレーション定義を、所定の定義に基づいてワンクリックで完了できます。
さらに、リレーションを貼った側からも対象が閲覧でき、単一のシナリオに複数のユーザーストーリーを紐付けた場合はシナリオ側からもユーザーストーリーの一覧を閲覧できる、孫ページからも情報を参照できる (ビジネスロジックテーブルからシナリオの情報を閲覧できる)、
など、とにかく要素間のアクセスしやすさを最大限に高めてくれ、これらをキーボードに1度も触れることなくclickベースの操作だけで実現できるのです。
打ち手②: データベースと複数のViewでページ遷移無しで情報を取得する
メリット:データベースを使い回して、用途に合わせたビューを表現できる
Wikiツールにおいては、情報そのものと見た目のデザインは同一の物なので、違う見た目のページを作りたい場合は、新しくページを作成する必要があります。当たり前ですね笑
一方で、Notionのデータベースは完全にViewと切り離されているため、用途に合わせて自由に見た目を調整する事ができます。
例えば、”シナリオ毎にユーザーストーリーの開発進捗を把握したい” という場合は、Group BY でシナリオを設定し(リレーションを使用)、タイムラインのビューに切り替えると便利です。
また、同一のデータベースを異なる基準で表示する事も出来ます。Group By で実装優先度を選択した状態でギャラリービューを表示してみます
これらの操作を “一切データベース記述を変更することなく” 実行する事ができます。前述のリレーション機能を組み合わせる事で、開発者が情報の在処に困ってしまうような場面は、設計次第でかなり減らせるのではないでしょうか?
仕様ドキュメントとしては、実装時期を把握するためにタイムライン表示をする、中身のプレビューをしながら一覧するためにギャラリービューを使う等がメインの使い方が便利そうです。
メリット:1つのデータベースページに滞在したままで、必要な情報を取得できる
また、一覧性という意味では、データベースの1行1行がそのままページになっているという点もポイントです。
従来のWikiツールですと、必要な情報を入手するまでに個別のページにアクセスする → 目的の情報が存在しなければ元の一覧ページに戻る というプロセスを経由しなくてはいけませんが、
Notionのデータベースでは、(1)仕様の情報がデータベース自体で一覧できる (2)1行1行がページとなっておりモーダルで即座に確認できる という事で、1つのページに留まりながら複数の情報を入手するアクションが取りやすくなっています。
これによって、特定のユーザーストーリーに紐付く詳細仕様を一覧する と言ったシーンで、1ページでスムーズに情報を取得できます。
細かい点ですが、小さいストレスを潰す事で、結果的により多くの人が利用するドキュメント体系が出来上がり、コミュニケーションコストの削減に役立つと考えます。
おわりに
今回は一部しか紹介できませんでしたが、API経由のアクセスに対応、RollUpで任意の集計が実行可能、そもそも動作が滅茶苦茶早いなど、他のドキュメンテーションツールと比較して優れている点が他にもあり、実際に使ってみて分かったTipsがあればまたご紹介できればと思います。
大規模データや機械学習モデルを取り扱う弊社のアプリケーションは、複雑な仕様を持つことも多く、こういったツールも取り入れてコミュニケーションを円滑にしながら、日々チーム開発を行っています。
採用も絶賛募集中ですので、是非興味のある方は、ポチっとどうぞ！https://www.wantedly.com/companies/jdsc/projects
