社内ドキュメント標準シリーズ(第1回) 〜 機能拡張仕様書編 〜

はじめに

みなさまこんにちは、さいとう(白)です。ConfitほかアトラスサービスのPdM/PjMを担当しています。これから何回かに渡って、アトラスの開発ドキュメントの話をしたいと思います。世間一般のIT企業のご多分に漏れず、アトラスでも仕様書や設計書、試験計画書などの開発ドキュメントを標準化しています。第1回となる今回は、機能拡張仕様書のドキュメント標準について書いていきます。

ドキュメントがない！有識者もいない！ソースコードが仕様だ！本当か！？そんな経験をしたことのある方はご存知かと思いますが、仕様書は大事です(笑)。初期開発フェーズではもちろんのこと、保守・運用フェーズ、その後の拡張フェーズにおいても、機能仕様が明示されていることで様々なロスを防ぐことができます。仕様書がないと、時間の経過によって記憶が薄れたり、担当者がいなくなったりしたときに、何が正しい挙動なのか誰もわからなくなってしまった、なんてことが起こり得ます。また、仕様だけでなく、そもそもの開発経緯や目的なども重要な情報になり得ます。アトラスサービスの開発・運用経験から、こういった「残すべきポイント」をおさえた仕様書の書き方をご紹介していきます。

機能拡張仕様書の記載内容

アトラスサービス開発における機能拡張仕様書の役割は、以前、CTO大神の記事で仕様作成プロセスとあわせてご紹介しています。端的に言えば、セールス・導入コンサルティング・システム開発の担当者間でゴールを共有し、達成に向けて必要なことを余すことなく議論し、議論した結果を明確に残し、開発・運用・保守すべてのフェーズで各担当者が迷わないようにするためのものです。

アトラスサービスの機能拡張仕様書は、以下のような章立てで構成しています。記載内容とともに説明していきます。

1. 開発概要

1.1. はじめに

機能拡張の概要を記載します。詳細は以降の章で記載していくので、ここでは「○○ロールで××を実現するための機能を開発する」のような簡潔な記述に留めます。

用語の定義

仕様書内で使われる用語は、この冒頭部分で定義します。読み手によって解釈が分かれそうなキーワードや、あまり一般的でない略語などがあれば一覧形式でまとめておき、ステークホルダー間で齟齬が生じないようにします。ODCのスタッフが開発を担当するプロジェクトでは、言語の違いによるコミュニケーションロスを減らすためにも、用語集が重要な役割をします。

1.2. 機能拡張の目的

1.2.1. 現状の問題・課題/解決すること

現状の問題や課題、解決すべきことを、その問題が生じている背景も合わせて記載します。こういうことができずにユーザーが困っている、問い合わせの要因になっているなど、具体的に記述します。問題が何らかの損失に結びついているのであれば、その深刻度合もあわせて記述するようにしています。開発の出発点にあたる問題提起の部分ですので、ここで間違ってしまうと効果的な機能拡張はできません。ステークホルダーの知見を総動員して、正確に問題を把握できるよう努めています。

1.2.2. 機能要件

上にあげた問題や課題に対する解決策を記載します。機能の詳細な振る舞いは「3.機能仕様」に記載するので、誰がどういう状況で何をできるようにする、といった最低限の記述に留めます。仕様検討の初期段階において、「この方法で本当に問題を解決できるのか？」「費用に見合う十分な効果を得られるのか？」を議論するために、要件を整理するものと考えればよいと思います。各ステークホルダーの合意を得て確定します。

1.3. 前提条件・制約事項

1.3.1. 制約事項

変更できない制約となる事項を記載します。仕様そのものに関するプロダクト的な要素もあれば、場合によってはスコープ、品質、コスト、納期などプロジェクトに関わる要素も出てきます。仕様作成後の工程にも強く影響するので、早めに明確にするようにしています。

1.3.2. 前提条件

機能仕様を作成する前提となる条件を記載します。こういう機能を実現するけれど、こういった例外的なケースには対応しませんよ、などといった条件を記述します。仕様検討フェーズでは、ステークホルダーとの議論を経て流動的に変わっていくことが多いです。

1.3.3. 利用規約の更新・影響

拡張内容によってはサービスの利用規約を更新することがあります。影響の有無を検討して、更新が必要であればその内容を記述します。場合によってはリーガルチェックを依頼することもあります。

1.4. 拡張対象機能

1.4.1. 機能構成

機能構成に変更がある場合は、ここに記載します。図表を用いてわかりやすく記述することを心がけています。拡張内容によって概念図やフローチャートなどを適切に使い分けています。

1.4.2. 対象機能

拡張対象の機能を一覧形式で記載します。ロール、機能名、機能概要(既存機能は変更内容)を記述します。拡張による影響範囲の洗い出しにも有効で、 漏れや不足があれば早い段階で有識者から指摘を受けて気づくことができます。

1.4.3. 想定件数

拡張機能のユーザー数や利用回数、データ件数などの想定件数を記載します。機能の特性により、時間あたりの件数なのか、オペレーション単位の件数なのか、それとも累計の件数なのか、記述すべき単位が異なります。ピーク特性がある機能に関しては、ピーク時の想定件数も記載します。過去の利用統計などから推測し、ある程度のバッファを見込んで設定しています。負荷試験や性能検証の際に、負荷レベルの目安になります。

1.4.4. サーバ・ミドルウェア構成変更

サーバ・ミドルウェアの構成に変更があれば記載します。どの機能においてどのような用途で利用するのか、といった概要と合わせて記述します。

1.4.5. リリース時付帯運用作業

機能拡張のリリースに伴う運用作業を一覧形式で記載します。サーバ・ミドルウェアの構成変更、データ変更、テーブル作成などの作業が漏れないよう、ここに記述していきます。実装方式により要否や内容が変わることもあるため、開発フェーズに入った後で更新する場合もあります。

1.5. データ移行作業

機能拡張に伴うデータ移行が必要な場合は、作業項目を一覧形式で記載します。こちらも実装方式により要否が変わることがあるため、開発フェーズで更新していくケースが多いです。

1.6. 関連ドキュメント

機能拡張により更新する設計書類を一覧形式で記載します。ドキュメントの更新漏れや作成不足の防止に有効です。

2. 機能実現方式

「3.機能仕様」に記載する機能単位の詳細な機能仕様では理解が難しい場合に、実現する機能の全体像と重要な機能の仕様を記載します。たとえばオプション設定による機能の振る舞いや出力内容が異なる場合のパターンやオペレーションによる登録データが異なる場合のパターン分けを図解で示します。また、外部サービスと連携する機能であれば、そのインターフェース仕様などについても記載します。

3. 機能仕様

このドキュメントの中で最もボリュームのある部分になります。機能単位で、機能の詳細な仕様や出力項目を記述します。設計・実装フェーズでエンジニアが迷わないよう図表も用いながら、エラーや異常時の挙動についても細かく記述していきます。
実際には、ロール、機能、サブ項目の章立てで「3.2.5.1. ×××××××」のように細分化して書くことが多いです。

4. 運用設計

4.1. 制約事項・課題など

機能拡張後の運用の注意点などを記載します。運用方法がこれまでと変わったり、新しい手順が増える場合には、導入コンサルティングチームへの申し送り事項として、漏れなく記述しておく必要があります。また、負荷耐久性や性能要求がシビアな機能では、「1.4.3. 想定件数」で想定した負荷レベルが実際の数値と乖離していないかなど、運用開始後にチェックする必要があるものを忘れないよう記載しておきます。

4.2. 作業一覧

機能拡張後の運用作業を一覧形式で記載します。作業項目、作業時期、作業概要を記述します。運用負担が重くならないか、重大な障害に直結するような危険な運用にならないかなど、運用リスクのチェックにも利用されます。

おわりに

いかがでしたでしょうか。今回は社内ドキュメント標準シリーズの第1回として、機能拡張仕様書の書き方をご紹介しました。Webデベロッパーのみなさまにとって、少しでも参考になれば幸いです。第2回以降も引き続き、アトラスのドキュメント標準を取り上げていきたいと思います。ご期待くださいませ。