【第1回】誰でも書ける…かも？わかりやすい仕様書を作るためのマイルール
この記事は2022/06/01に作成されました。
「これから作るものが満たすべき条件や内容を明確化してまとめた文書」
それが仕様書です。
製品やサービス、ソフトウェア開発など…多くのものが目に見える形になる前は、文書でまとめられている事がほとんどです。仕様書を作ることで、同じプロジェクトに関わる人達の間で認識に差が出る事を防いだり、途中の仕様変更による工数増加も防ぎやすくなります。
このように仕様書は「我々が作ろうとしているものは何なのか」を明確にし、忘れないようにするための非常に大切な書類なのです。
そんな仕様書を…どうしても書かなきゃならない時ってありますよね？私は何度もあります。
正直かなり面倒臭い作業ですが、自分でゼロ状態からシステムやストーリーを構築していける、とても面白い仕事でもあります。
皆んなにもそんな気持ちを味わってみて欲しい...！と、ある日思ったので、仕様書を書く上でのマイルールを紹介してみようと思います。
記念すべき第1回は、
「わかりやすい文の書き方と鋼鉄のルール編」
です。主に私が仕様書を書く上で必ず気を付けている文の書き方や言葉の使い方について書きます。具体的な手順等は次回説明できればと考えていますのでお楽しみに！
必ず気を付けていること
仕様書を書く上で、私は以下の揺るぎない鋼鉄のルールを自分に課しています。
- 形容詞・形容動詞の使用禁止
- 接続語の使用は最低限かつ適切に
- 聞き慣れない言い回しをしない
- 何度も同じ言葉を使わない
- 簡潔にする
ということです。上から順に説明していきます。
①形容詞・形容動詞・副詞の使用禁止
これは本当に単純な理由です。必要ないからです。あっても邪魔です。却って認識に差が生まれる原因になります。もし入れてる人がいたら今すぐやめてください。本当に邪魔です。
つまり...どういうことだってばよ？という方のために、例も一緒に紹介します。
例1：やってることは結局同じなら...
×：マウスをゆっくり移動させて実行
○：マウスを移動させて実行
これは簡単ですね。どちらも最終的には「実行」という動作に辿り着いています。故にその間の様子について語る必要はありません。
例2：形容詞は人の基準に依存しやすい
×：ボタンを押すとなめらかに上にスライドします
○：ボタンを押すと3秒かけて上にスライドします
「なめらか」の基準は人により違います。形容詞は、実装時に「思ってたのと違う！」と他者から言われる可能性もあるため使わないようにします。もし動作について詳しく述べるなら時間や距離も併せて書くなど、動作の例を明記しておいて認識に差が生まれないようにしましょう。
接続語の使用は最低限かつ適切に
接続語は多用するとわかりにくい文になりやすいです。また、接続語の誤用は違和感や解釈の違いを生みやすいです。あくまでも必要最低限に正しく使うようにします。
例1：わざわざ使わなくても....
×：会員にはノーマル、シルバー、ゴールドがいます。つまり、3種類の会員区分があります。
○：会員にはノーマル、シルバー、ゴールドの3種類の会員区分があります。
例で使われている接続語は「つまり」です。カットすることでスっと頭に入りやすい文章が作れます。
例2：他の意味を含みがちな使い方はしない
×：一度選んだカテゴリーは変更できませんが、追加は可能ではあります。
○：一度選んだカテゴリーは変更できませんが、追加は可能です。
結局追加ができるのなら、「できます、可能です」と言い切りましょう。「可能ではあります」だと他の可能性を感じる文となり、読んでいて釈然としません。
聞き慣れない言い回しをしない
文書なので難しい言葉や言い回しを使ってみたくなる気持ちもわかります。
しかし、仕様書の目的は人との認識の差を埋めることです。特に指定がない限りは、わかりやすく聞きやすい言葉を使用します。
例1：言えたら確かにカッコイイけども
×：会員料金が毎月500円発生しますが、この会員がゴールドである場合はこの限りではありません。
○：会員料金が毎月500円発生します。会員がゴールドである場合は無料です。
「この限りではありません」という言葉、あまり聞き慣れないのではないでしょうか？表現としても回りくどいように感じます。おまけに、長い文章の割にゴールド会員の場合の料金について明確になっていません。
○の方が簡潔かつ、ゴールド会員の場合の料金についても早い段階で述べることができています。
例2：この漢字...自分はちゃんと読める？
×：エディターの右上のボタンを押下することで、プレビューを表示します。
○：エディターの右上のボタンを押し、プレビューを表示します。
わざわざ難しい言葉を使用せずとも同じ意味の文章は作れます。ただ、仕様書を見せる相手にもよるので臨機応変に言葉を選ぶようにしましょう。
何度も同じ言葉を何度も使わない
たまに1文に話題が2個も3個も同時に存在していて、要点がわかりにくい文を見かけることがあります。また、これをやりがちな人は句読点の扱いも苦手な事が多い印象があります。
例1：今何回目？
×：会員区分の変更には手続きが必要となり、会員区分変更手続きフォームから会員区分変更の申し込みが行えます。
○：会員区分を変更する場合、専用フォームから手続きの申し込みができます。
「会員区分」「変更」「手続き」という言葉を多用しすぎです。
「専用のフォームから変更手続きの申し込みが可能」という事が伝われば良いので、まずはそれを明言します。その後、必要に応じて「専用フォームとは何なのか」についてきちんと説明をします。
例2：そもそも、区切ろう？
○：会員区分を変更するには手続きが必要です。会員区分変更手続きフォームから、変更申し込みが行えます。
急に今まで登場しなかった言葉を使うのに抵抗がある場合は、話題が変わる部分に句点を挟んで文を区切ります。
上記の例では「必要な動作」と「どこからその動作が行えるか」の2つの話題を別々に述べることができており、一気にクリアな印象の文章になります。
簡潔にする
これまで4つの鉄則のルールを紹介しました。どのルールにも共通しているのが、「簡潔にする」ということです。できるだけ無駄を省き、読んだ人が飲み込みやすい文章を作ることが大切です。
例1：表現の仕方は文のみに非ず
×：全ての会員は会員区分に関わらず、毎月クーポンコードが発行されます。ノーマルでは100円引き、シルバーは300円引き、ゴールドは500円引きのクーポンコードです。
○：全ての会員に毎月クーポンコードが発行されます。会員区分それぞれの値引き内容は以下の通りです。
・ノーマル：100円
・シルバー：300円
・ゴールド：500円
文章がダラダラと長くなる場合は箇条書きリストもぜひ活用しましょう。これだけでずっと読みやすい文書を作ることができます。
例2：世界には見出しという文化があってですね...？
×：記事はHTMLとCSSの欄がそれぞれ設置されている、エディターフォームを使用して書きます。公開日を指定する場合は公開日という項目の中にあるセレクトボックスから任意の日付を選びます。
○：
★記事の書き方
エディターフォームを使用します。エディターフォームにはHTMLとCSSの欄があります。
★公開日の指定方法
「公開日」の項目内にある、セレクトボックスから任意を日付を選びます。
手順の説明は見出しを使ったり、番号リストを使うと非常に読みやすくなります。短い文でも話題が変わる場合は見出しを付けてみてください。
無駄のない読みやすい文章を作れるよう練習あるのみ
仕様書はプロジェクトに関わる人達、皆んなが読むものです。趣味色が強い小説等ならともかく、仕事で使う書類ですから混乱を与えにくい文章を作れるようになりたいものです。
いざ書こうとしても、すぐにわかりやすい文を作れるわけではありません。普段から無駄がない、簡潔な文を作れるように練習しましょう。メールやメッセージツールはもちろん、文を書けるのならSNSなどでも練習できます。
是非とも「自分以外の誰かが読むんだ」ということを念頭に置いて、練習してみて下さい。
次回は本格的に書き方の解説に移っていきたいと思います！
