いわゆる「エンジニア」じゃない人が要件定義とか設計書について考えてみたよ

社内でドキュメントをちゃんと作ろう！！という流れが起きているので、その波に乗るために調べたり考えたりしたことをまとめました。
この記事を書いているのはデザイナーでもなければエンジニアでもない、
だからと言ってhtmlコーダーとかwebディレクターかと聞かれるとちょっと微妙な人です。
普段はデザイナーやhtmlコーディングをしたりCMSのテーマを作ったりする人たちと同じチームにいます。
あくまで個人の感想です。

要件定義ってなに？

要件定義とは、システム開発などのプロジェクトを始める前の段階で、必要な機能や要求をわかりやすくまとめていく作業のことです。企画の進行とともに要件定義に立ち返ることも多く、目的の脱線を防止する役割も果たします。

「要件定義」でggって一番目に出てきたページです。

• お客さまがどんなものがほしいと言っているのか
• それを満たすためにどんな仕組みが必要なのか

をまとめることを要件定義というのだと理解しました。

じゃあ要件定義書ってなに？

概要と構想
システムの概要や、どのような仕上がりになる予定なのか、プロジェクトの全体的な概要と目的予想を説明します。
ユーザーの要求と必須要件
「こうして欲しい、この機能が欲しい」というユーザーの要望と、開発側で出た必須要件を記載します。機能要件以外に、非機能要件など複数の要件がある場合は、カテゴリーで分けて見やすくしましょう。
目標や目的
システムを導入する目的、それによって得られるメリットなどを記載することで、ユーザー側もイメージが掴みやすくなります。

また、要件定義書はユーザー側も確認するため、開発の知識がない人も理解できるように専門用語は省きます。システム開発の基盤になる要件定義書は、全体像から詳細まで矛盾がないように作成するのが大切です。

↑と同じページから引用しています。
要件定義書は要件定義で決まった内容を、お客さまがわかるようにまとめなおしたものになるのかな？と思いました。

設計書はなんなの？

基本設計書
基本設計書とは、要件定義の内容を受けた上で、具体的なシステムに落とし込んでいくための基本的な設計書です。どのような機能をユーザーが求めているかを要件定義書を読みながら確認し、「機能に落とし込むとしたらどうなる？」ということを基本設計書にまとめます。システム化の背景を押さえた上で、システム化の対象範囲がまとめられているか、業務フローはどうなっているのかなどがまとめられていることが重要です。基本設計を固めておくことで、後ほど発生する手戻りのリスクを減らし、円滑なシステム開発を実現できます。詳細設計よりはカジュアルなまとめ方で構いません。

詳細設計とは
詳細設計は、基本設計において固めていたシステムの全容を、具体的な機能に落とし込んで設計する段階です。基本設計では、必要な要件などを確認しながら、システムの全体像を構築していく必要があります。それに対し、詳細設計では開発に向けて仕様の詳細をまとめ、プログラムによってこれらを実現するためのものです。詳細設計をおろそかにしてしまうと、後々になって「機能の実装ができない」「実装したいものが曖昧でニーズに応えられているかわからない」といったトラブルが出てきてしまいます。詳細設計は、クライアントにとって満足のいくシステムにするために必要なプロセスであると同時に、現場のプログラマにとっても重要な役割を担っています。

プログラム設計書
プログラム設計書とは、システムの開発を進める上で、どのようにコーディングを行えば良いのかの設計をあらわしたものです。詳細設計書における一部パートと考えられており、同義的に使われることもあります。プログラム設計書の目的は、「仕様書の通りにプログラミングすれば、問題なくシステムが完成する」という状況を作り出すためです。詳細まで設計を行うため、実用性の高い書類であると言えます。逆を言えば、詳細まで丁寧に記述しておかなければ、下流工程で修正などが多く発生する恐れもあります。

「設計書」でggって上から4番目に出てきたページからの引用です。いろいろ種類があるんですね～。
要件定義書に書かれていることを実際にプログラムに落とし込むときに「どうやってするのか」をまとめたものが設計書なんだろうな、と思いました。
基本設計書でざっくりまとめて、詳細設計書で具体的な仕様の詳細をまとめて、プログラム設計書で実際にどんなコードを書くのかをまとめているんですよねきっと…。

全部書くのめちゃくちゃ大変じゃないですか？

正直な感想ですｗ
大きな案件や人が潤沢にいるのであれば書けるのかもなと思いましたが、本当に小さい1人日もないような案件でも要件定義書や設計書を全部書いていたらめちゃくちゃ大変ですよね…。
弊社の開発チームの人に聞いてみても同じような所感を持っているようでした。

じゃあどうしよう

冒頭に書いたドキュメントをちゃんと作ろう！！の流れで開発チームのみなさんがひな形を作ってくださったので、わたしもそのひな形を流用させていただくことにしました。
また、実際に書いた設計書を共有していただいたりもしています。
（開発チームのみなさんありがとうございます）
が、わたしの仕事は難しいプログラムを書いたり複雑な仕組みを作ったりするようなタイプではないので、ちょっとアレンジを加えることにしました。

わたしがかんがえたさいきょうのCMSを使うwebサイトの要件定義書・設計書

わたしは主にCMSのテーマ構築やCMSで作ったデータを取り出してjsやphpなどなどであれこれする仕事をしてます(なんという職業だと名乗ればいいのかわからない)。
弊社だとちょうどwebデザイナーさんともフロントエンド/バックエンドエンジニアさんとも微妙にかぶらないようなことをしているので、それに合いそうな書き方にしてみます。

たとえばWPでこんなかんじのサイトを作るとしたらどんな風に作るか書いていこうと思います。

• スライダー(TOPページとかによくあるやつ)
• 記事一覧
• カテゴリ一覧
• タグ一覧
• 記事詳細
• ページネーション
• メールフォーム
• サイト内フリーワード検索
• 他所のサイトの記事一覧

要件定義書

これについてはおそらくエンジニアさんたちが書いているものをなぞる形でよいと思いました。
ただしWordPressやMovableTypeなど、自分で開発していない仕組みの上にものを載せることになるので、CMSについての話はほとんど触れないことにしています。
自分で作っていないので確実にこうこうこうです～とは言えないですし、お客さまもCMSを使うことを了承しているはずなので書く意味がないかな～と思っています。

設計書

各設計書には用語集を付けるとよいみたいです。(弊社の開発者にもらったやつにはついてた)
たしかに、言葉の定義を決めておかないと取り違えられちゃったりすると面倒ですもんね。

基本設計書

この設計書はざっくりどうつくる？を内容なので、
「なにをするためにこんなかんじのことをします、具体的にどうするかは別のドキュメントに書きます」
という内容を書けばいいのではないかな～と思っています。
とはいえ自分で1から実装する機能っぽい機能はないので、ざざっとどんなことをするのか列挙していくような感じになります。
↑で書いたこれを、どこに設置するのか、も含めて書くかなあと思っています。

• スライダー(TOPページとかによくあるやつ)
• 記事一覧
• カテゴリ一覧
• タグ一覧
• 記事詳細
• ページネーション
• メールフォーム
• サイト内フリーワード検索
• 他所のサイトの記事一覧

詳細設計書

CMSの仕組みを流用しない部分について概要を書けばいいんじゃないかな～と思いました。
大したものではないのであれば書くこともないので省いてしまってもいいのかもと思ってます。
今回の例だと

• スライダー(TOPページとかによくあるやつ)
• 他所のサイトの記事一覧

これがどんなものかを書きます。
スライダーで使うプラグインはどれですよ、プラグインファイルはCDN/自サイトで持ちますよ、このオプションを使いますよ、
他所のサイトの記事一覧はどこどこのサイトのjsonを取ってきたりAPIをたたいてデータを持ってきたりしてforeachすしますよ、何をサイトに表示しますよ、
というようなことを書くだろうな～と思います。

プログラム設計書

実際にどうコーディングするか、具体的に書いていくやつだよな～と思っています。
例えばカテゴリ一覧だったらこんな、こんなサンプルコードを書きます。

// カテゴリ一覧を表示
<ul class="catlist">
<?php
$cat = get_categories();
foreach ($categories as $category) {
    echo '<li><a href="' . get_category_link($cat->term_id) . '">' . $cat->name . '</a></li>';
}
?>
</ul>

本当は日本語で書いたほうがいいのでしょうが、そこはいつかできるようになれればいいかな…と思っています…。

まとめと感想

要件定義書も設計書も、これから作るwebサイト(システム)はどんなものですよ、こうこうこういうふうに作りますよ、
という内容をまとめて、チームもお客さまも迷子にならないようにする道しるべなんだろうなあと思いました。
また、こういったドキュメントは「どんなものを作ったのか」という記録にもなるので、
リリース後、サイト更新チームに引き継ぐ際にめちゃくちゃ役に立つ資料になるんじゃないかな～と思いました。

デザイナーさんもhtmlコーダーさんも、案件を進めていくうちに何を作ってたんだっけ？？とか、
既にリリース済みのサイトのここを更新したいけどどうなってんの？？となることって結構ありませんか？
こういったドキュメントはエンジニアさんだけが作ったり読んだりするものではないので、ぜひ業務に取り入れてみてはいかがでしょうか。
最初は面倒に感じるかもしれませんが、自分の中である程度のひな型ができるとすいすい書けるようになる…はず！！

webに関わるみなさんの役に立つ記事になっているといいな～と思います。
ではまた明日。