specifications - 良いスペックとは？

Question

ジョエルテストの項目の 1 つは、プロジェクト/会社が仕様を持っている必要があるということです。

何がいいスペックなのか気になります。一部の企業は、誰も読まない役に立たない仕様を大量に作成しますが、他の企業は、「とにかく誰も読まない」という理由で何も書き留めません。それで、あなたはあなたの仕様に何を入れますか？両極端の良いバランスとは？本当に、本当に (!) 常に仕様に記録する必要がある、特に重要なことはありますか?

score 54 · Accepted Answer

最高の仕様は次のようなものです。

存在する
方法ではなく、何を説明するか (解決策なし)
できるだけ少ない方法で解釈できる
広く分布している
関係者全員が仕様であると合意している
簡潔です
一貫性がある
要件の変更に応じて定期的に更新される
可能な限り実用的な問題を説明します
テスト可能

score 14 · Accepted Answer

スペックに入れるもの

あなたはスペックの聴衆を見て、彼らが知る必要があることを理解する必要があります。それはあなたとビジネススポンサーの間の単なる文書ですか？この場合、おそらくかなり軽量になる可能性があります。100人年以上のJ2EEプロジェクトの機能仕様である場合は、おそらくもう少し詳細が必要になります。

聴衆

重要な質問は次のとおりです。誰が仕様を読むのか-仕様には、いくつかの潜在的な利害関係者のセットがあります。

システムをサインオフしているビジネスオーナー。
システムを構築している開発者（あなたである場合とそうでない場合があります）
そのためのテスト計画を書かなければならないQAの人々。
システムを理解したいメンテナンススタッフ
他のシステムをプロジェクトに統合したい他のプロジェクトの開発者またはアナリスト。

典型的な主要な利害関係者の要件：

ビジネスオーナーは、システムワークフローとビジネスルールが何であるかを明確に理解して、合意した内容を理解するための戦いのチャンスを得る必要があります。それらが仕様の唯一の主要な対象者である場合は、ユーザーインターフェイス、画面画面のワークフロー、およびビジネスとデータの検証ルールに集中してください。
開発者は、データモデル、データ検証ルール、ユーザーインターフェイス設計の一部またはすべて、および予想されるシステム動作の十分な説明を必要とします。これにより、開発者は何を構築するかを知ることができます。開発者向けに作成している場合は、ユーザーインターフェイス、データモデルへのマッピング、およびユーザーインターフェイスのルールに集中してください。これは、2つのサードパーティ間のコミュニケーションの仲介者として機能しているため、自分で開発を行う場合よりも詳細にする必要があります。

2つのシステム間のインターフェースを指定する場合、これは非常に正確である必要があります。
QAスタッフは、アプリケーションのロジック、検証、および予想されるユーザーインターフェイスの動作をテストおよび検証する方法を理解するために十分な情報を必要としています。開発者とQAスタッフを対象とした仕様は、かなり明確である必要があります。
保守スタッフは、開発者とほぼ同じ情報に加えて、アーキテクチャを説明するシステムロードマップドキュメントを必要とします。
インテグレータには、データモデルとインターフェイスの明確な定義が必要です。

仕様の主要コンポーネント：

ビジネスアプリの仕様を書いていると思いますので、以下の内容はこれに合わせたものです。他のタイプのシステムの仕様は、異なる重点を置いています。私の経験では、機能仕様の重要な要素は次のとおりです。

ユーザーインターフェイス：画面のモックアップと、システムの相互作用動作および画面間のワークフローの説明。
データモデル：データ項目の定義とユーザーインターフェイスへのマッピング。ユーザーインターフェイスのマッピングは通常、ユーザーインターフェイスを説明する仕様のビットで行われます。
データ検証とビジネスルール：定義とともに、データに対してどのようなチェックを行う必要があり、どのような計算が行われているのか。ここでは例が非常に役立ちます。
インターフェイスの定義：他のシステムが使用できるインターフェイスを公開している場合は、それらをかなり厳密に指定する必要があります。より単純なインターネットRFCは、プロトコル設計の非常に優れた例を示しており、インターフェイスドキュメントの例の良いスタートを切る必要があります。インターフェースを明確に定義することは簡単ではありませんが、ほぼ確実に、将来の苦痛を軽減します。
接着剤：これは、ユースケース、ワークフロー図、およびその他の要件に関連するアーティファクトが役立つ場所です。一般に、これらの完全なリストは無意味ですが、このタイプのドキュメントがアイテムをコンテキストに配置するのに役立つシステム内の重要な領域があります。私の経験では、ユースケースやその他の要件レベルの説明を選択的に含めることで、仕様に明確さと意味を追加できますが、システムとのすべての対話についてユーザーストーリーを作成するのは時間の無駄です。

Joel（「ソフトウェアで」の名声）は、これについて、痛みのない機能仕様と呼ばれる一連の優れた記事を書きました。これは、私が何度も人々に紹介したものです。それはかなり良い記事のセットであり、読む価値があります。私の意見では、あなたの目的は、あいまいさを最小限に抑える方法でシステムが何をすることになっているのかを明確に説明することです。仕様を参照ドキュメントと考えると非常に便利です。さまざまな利害関係者が簡単に調べられるようにしたいと思うかもしれません。

スペックに関する箇条書きのグリブセットを書いたので、明確なコミュニケーションの部分は見た目よりも難しいです。仕様は実際には重要な技術文書であり、技術的な執筆と編集のスキルのかなりのテストです。あなたは実際、誰かが作成することになっているものを説明するドキュメントを書く仕事をしています。良いスペックをするのはちょっとした芸術です。

スペックを実行することの見返りは、他の誰もそれらを実行したくないということです。システムにとっておそらく唯一重要なドキュメントを書いたので、ショットを呼び出すことができます。議題を持っている他の人は、仕様を変更するようにあなたに働きかけるか、何らかの形でプロジェクトに競合する仕様を課す必要があります。これは、ペンが剣よりも強力である良い例です。

編集：「どのように」と「何を」の違いについて議論するのは私の経験であり、かなり自己奉仕的である傾向があります。重要なプロジェクトでは、データモデルとユーザーインターフェイスに複数の利害関係者がいますが、そのすべてがシステムの開発者であるとは限りません。データウェアハウジングで作業することで、アプリケーションデータモデルが自由になることを許可されたときに生じる混乱を味わうことができます。PFSは、仕様が対応しなければならない潜在的な利害関係者のセットを感じさせる必要があります。

誰かがデータモデルまたはユーザーインターフェイスデザインを所有しているという事実は、これらが単にフラットによって決定されることを意味するわけではありません-談話と交渉のプロセスが存在する可能性があります。ただし、プロジェクトが大きくなるにつれて、所有権の価値とこれらの一貫性が大きくなります。良いアナリストの価値を評価する最良の方法は、悪いアナリストによる被害を確認することであるというのは、過去の私の観察です。

score 11 · Accepted Answer

私の経験では、仕様に次のものが含まれている場合、仕様が読まれる可能性が高くなります。

可能な場合は図を使用してください - 写真は 1000 語に相当します
仕様が何を説明しているかを明確に示すタイトルページを用意する
ドキュメント全体で使用されるスタイルを持っています。すべてのヘッダーを同じフォント、サイズ、スタイルにします。フォントをずっと同じにする、同じ箇条書きのスタイルを使うなど
ワッフルしないでください - 簡潔で要点を明確にし、ドキュメントを埋めるために余分なくだらないことを追加しないでください。ポイントが数行のテキストで説明できない場合は、さらに細分化する必要があるかもしれません

仕様を書いている人がシステムを理解していない会社を見てきました。これは、仕様を書くことによってシステムを学習する方法に近いものです。これは通常、涙で終わります...

score 4 · Accepted Answer

クライアント向けに特注のソフトウェアを開発する人として、最良の仕様は顧客が署名したものです。

仕様がどれほど洗練されているかは関係ありません。顧客が書面で明示的に同意していない場合は、仕様を変更し、変更をシームレスに処理して、美しいアーキテクチャを破壊することを期待します...

score 2 · Accepted Answer

優れた仕様には、測定可能で検証可能な要件が含まれている必要があります。各要件を見ると、「この要件を満たしていることをどのように証明できますか？」という質問に簡単に答えられるはずです。

score 1 · Accepted Answer

プロジェクトの規模と（すべてのアーキテクチャの決定と同様に）制約が何であるかによって異なります。良いスタートは

簡単な説明、「1ページャー」
コンテキスト図-境界はどこにあり、システムと相互作用するものは何ですか？
ユースケース/ユーザーストーリー
GUIプロトタイプまたはペーパープロトタイプ（該当する場合）
必要な非機能要件（パフォーマンスなど）の説明

何よりも、受け入れテスト、つまり、チェックできることのテスト可能なステートメントと、それらのことが行われるとプロジェクトが完了するという合意を行うことです。

score 1 · Accepted Answer

Joel Test 記事のフォローアップであるJoel の一連の「無痛機能仕様」をお読みください。それらは、"Joel on Software" 本にも掲載されています。

score 1 · Accepted Answer

また、ユーザーが持っている目標や、特定の機能の全体的な考え方を述べるところから始めると役立ちます。正確な実装を埋めるのではなく。これは常に、オープンマインドを絞り込むか、創造性に欠ける (より使いやすい) ソリューションを使用するように感じます。したがって、「すべてのオプションを開いたまま」にしておく必要があります。

例 "X" を測定するソフトウェアを作成します。

述べる代わりに: 開始ボタンと保存ボタンが必要です。

使用: ユーザーは、測定を開始して保存できる必要があります。

なぜですか？最初の状況では、ソリューションがどうあるべきかをすでに決定しているのに対し、2 番目の状況では、何かを実装する方法について柔軟性が得られるからです。これは些細なことのように思えるかもしれませんが、「プログラマー」は問題 (または状況) よりも解決策を考える傾向があると感じています。より多くの機能を追加すると、ウィザードを使用したり、プロセスを自動化したりする方が良いかもしれないため、これはより明白になりますが、アイデアはボタンの使用にすでに絞り込まれています。

score 0 · Accepted Answer

0

「ユースケース」を書くと、ページの束を節約できると思います

于 2008-12-18T21:36:55.263 に答える

score 0 · Accepted Answer

実装に必要なすべての重要な情報を記述した青写真ですが、必要な些細な情報や明白な情報をすべて記述するために努力を無駄にすることはありません。

必要のない余分なノイズを提供することなく、実装が「期待どおり」であることを保証するのに十分な情報である必要があります。

実際には、ほとんどの人はこれを誤解しています。簡単なこと (最も必要性が低いもの) に集中し、難しいこと (本当にロックダウンしたいもの) を敬遠するからです。私はあまりにも多くの 2 インチの文書が要点を完全に、完全に見落としているのを見てきました。

仕様は長くする必要はありません。適切なものが含まれている必要があります。

(ヒント: プログラマーがコーディング中にそのページを見なかった場合、それはおそらく必要ではありませんでした)

ポール。

score 0 · Accepted Answer

+1 @ KiwiBastardと私は write bullet-like を追加し、各箇条書きをテスト可能にします。

specifications - 良いスペックとは？

12 に答える 12

Related

Reference