blog 開発

【要件定義の注意】単語を統一させる

今回は、自戒を込めて記事を書いていきます。
何度も注意されてしまったので、ぜひ皆さんもこれは意識していきましょう。

想定読者

  • 駆け出しエンジニア
  • 要件定義を初めて書くエンジニア

では僕の注意された要件定義を見ながら復習していきましょう。

要件定義を書くときのポイント

ポイント

  • 読んだ人が文章だけでどんなアプリかを想像できるように記載する。
  • ビジネスライクな文章で記載する。
  • 単語を統一する。
すずき

上記をチェックしながら要件定義を書いていきましょう。

要件定義のフォーマットを置いておきます。

【アプリケーション名】

【アプリケーションの概要】

【どんな画面があって、どんな機能があるか】

【アプリケーションは何で作るか】※技術スタックを書けばいいです

参考に鈴木の要件定義は下記から見れます。

すずき

ただ上記の修正でも指摘をいただいたので、自戒を込めて今回の記事を書いているよ!

読んだ人が文章だけでどんなアプリかを想像できる

これは別にエンジニアじゃなくても大切だなと思いました。
自分がわかればいいやと1回目の要件定義では記載してしまい、これどういうこと?と突っ込まれることが多かったのもここです。

これも悪い例と修正版の中から抜粋して見比べてイメージを掴んでいきましょう。

悪い例

パソコンで使える簡単なタスク管理アプリ
シンプルに登録したタスクが一覧表示されているTodo形式
タスク管理なので、期限もわかりやすくするためにガントチャートも表示する。

すずき

はい、ダメですね。下記ご指摘内容です。

「シンプル」という言葉は概要としては重要な情報ではありません。
鈴木さんの文章では、登録するタスク内容がシンプルなのか、登録する操作方法がシンプルなのか、はたまた両方なのか伝わりません。

確かに読みかえしてみると、まさにご指摘通りなんでそう書いてしまったんだろうと思いました。w
話し言葉で「シンプルに」をよく使ってしまうので、相手にわかりやすく伝えると言う点では、こういった自分にしか伝わらない抽象的な言葉をなくしていくことが重要だと思います。

修正版

迷わないシンプルな操作性でタスク管理ができるWebアプリケーションです。
ユーザーはタスクを登録し、それらのタスクを一覧表示で確認できます。

タスクの一覧表示形式は一般的なTodo形式と同様です。
一度登録したタスクは、内容の更新やタスク自体の削除が可能であり、完了したタスクには完了ステータスを付与できます。
さらに、タスクには期限の設定が可能で、複数のタスクの期限を可視化するためにガントチャート形式の表示も行います。

すずき

だいぶイメージできるレベルにまでなったんじゃないでしょうか!

上記のような形で、アプリケーションの概要は、相手が文章だけで、イメージでき何をするのかパッとわかるような文章を心がけて書いていく必要があります。

ビジネスライクな文章で記載する

すずき

これは、本当に年齢のせいにしながら逃げてきましたw
恥ずかしいですが、悪い例を見ていきましょう。

悪い例

パソコンで使える簡単なタスク管理アプリ

→もう少し、ITな表現をしましょう。特に「パソコンで使える」とかは表現として幼稚です。

ぐさっときましたw
ここで言い訳をかましておきますが、やはり営業マンとして、お客様に通じない言葉を喋るのはよくないのです。そのため全ての言葉に対して、噛み砕いて喋る必要があります。固くなるような発言をするのではなく........言い訳でした。

修正版を見てみましょう。

修正版

迷わないシンプルな操作性でタスク管理ができるWebアプリケーションです。

すずき

自分以外が読むと意識した文章になっていますね。
「パソコンで使える」は幼稚です!!w

単語を統一する

すずき

今までの2つも重要でしたが、すずき的に一番重要です。

エンジニアの方であれば特に意識しなくても大丈夫かもしれませんが、未経験エンジニアの皆さん十分に注意してください。
正直一番意識しないと僕はスルーしてしまうので、自戒を込めて書いていきます。
まずは悪い例を見てましょう。

悪い例

  1. ユーザー登録画面
    ユーザーの新規登録を行う画面です。
  2. ログイン画面
    登録したアカウントでログインする画面です。
すずき

これ皆さん何が悪いか気づきましたか?

これは、ユーザーとアカウントが同じ意味なのにもか関わらず違う表現をしてしまっていることです

ユーザーという言葉と同じ意味で言っているのは分かりますが、言葉は可能な限り統一しましょう。
この指摘はこれで何度目かです。
正味、どっちでもいいのでは?と感じているかもしれませんが、実際の開発ではこういった用語を適当に扱うと必ず事故を起こします。
難しい用語が出れば尚更。この簡単なレベルでの統一から慣れるようにしてください。
また、複数回同じ指摘を受けているのは、指摘を適切に受け止めていないことの表れです。
気を引き締めて取り組むようにしましょう。

指摘を受けても直せなかったのは、おそらくこれをしてしまったことによる事故がどのレベルなのか把握できていないからだと思います。例えば、変数をとってしても、サインアップ画面とログイン画面を作る際に、サインアップでは、変数名をユーザーにしているのにログイン画面では、アカウントという変数名で作ってしまうようなミスがこの簡単な単語で起こってしまうかもしれません。

今の僕の経験値では、この規模ですみますが、大規模開発で同じミスをしたらどんなエラーが待っているかわかりません。なので、日頃からこういった単語の統一を文章などを書く上でも意識して修正していく必要があると思いました!!!

すずき

まじで自戒を込めて!

まとめ

ポイント

  • 読んだ人が文章だけでどんなアプリかを想像できるように記載する。
  • ビジネスライクな文章で記載する。
  • 単語を統一する。

上記を再度意識しながら、エンジニアの仕事をしていきたいと思います。正直コードを書く前にここまでつまづくとは、根底の意識改革から始めた方がいいと思いました。

世の中で営業マンとエンジニアが仲悪いのは、この思想によるものな気がする。エンジニアは、初期段階からガチガチに設計して細かいところも見落とさずに進めていくのに対して営業は、はじめは簡単でいいから走りながら修正していこうっていう頭なので双方がバチバチになる理由がわかりましたw

すずきは抜群な営業脳なので、これから半分はエンジニア脳になるように意識していきます!

  • この記事を書いた人

鈴木陽介

現役Javaエンジニア

2000年生まれ

もうすぐ書籍を出版します。

-blog, 開発