どうも、iinoです。株式会社ナレッジワークでQAエンジニアをしています。
今回は社内のLT大会で発表した内容を記事にしてみました。
社内のLT大会については、同日の登壇仲間である torii さんが、彼の発表内容をまとめた記事内で紹介してくれているので、そちらをご参照ください！
社内のLT大会ということで、登壇資料には「minispec」「DesignDoc」「TestDesignDoc」などの社内用語を使用しています。本記事内では一般的な用語に置き換えるようにしていますが、興味がある方は以下もご参照いただけると嬉しいです。
はじめに
今回取り扱う内容は『分かりやすい、読みやすい文章の書き方』・・・ではありません！
私が普段、設計ドキュメントのレビューやテスト設計ドキュメントの作成をする際に意識していることのご紹介です。
なぜ日本語にこだわるのか？
ソフトウェア開発では、誤解や勘違いがバグの種になると日々感じています。
特に、仕様案や設計ドキュメントで誤解や勘違いが生じると、のちのち面倒なバグになる可能性が高いという実感があります。
日本語にこだわることで、誤解や勘違いを防げる！あるいは、気づくキッカケを得られる！
・・・かもしれない。
そんな思いから日本語にこだわるようになりました。
こだわり その1：
『主体』、『対象・データ』、『機能』の表現にこだわる
格好つけた書き方してますが、噛み砕くと、 誰が・何を・どうする の表現にこだわっています。
主体 →「誰が」
「誰が」という部分を意識して、能動態（～する）と受動態（～される）を書き分けるようにしています。
例えば、
必須項目が未入力の状態で「保存」ボタンを押したら、アラートを表示する
という仕様があるとします。特に違和感ないようにも思えますが、実は、この文章には2つの主体が存在します。
ボタンを押すのはユーザーの操作であり、アラートを表示するのはシステムの機能です。
これを、主体をシステムで統一、あるいは、ユーザーで統一するようにすると、次のようになります。
- 必須項目が未入力の状態で「保存」ボタンを押 され たら、アラートを表示する
- 必須項目が未入力の状態で「保存」ボタンを押したら、アラート が 表示 される
今回の例のようなシンプルな文章であれば、こだわらなくても誤解や勘違いを生むようなことは少ないと思います。ですが、ユーザーの種類が複数あったり、関係するシステムが複数あったりする場合など、「誰が」（あるいは、「何が」）が増えていくと、リスクも高まってくるのではと考えています。
日本語は主語を省略できてしまうので、関係する人やシステムが多ければ、主語も明記した方がよいこともあるかもしれません。
ただ、主語まで書くと文章がしつこくなり、かえって読みづらい・分かりづらいものになってしまうことが多いので、せめて主体は統一するように気をつけています。
対象・データ →「何を」、機能 →「どうする」
「何を」に該当する対象やデータは名詞で、「どうする」という機能に関する記述は動詞で書くようにしています。
例えば、「更新」ボタンがクリックされたときの機能仕様に
入力値の保存を行い、トーストで完了メッセージを表示
と書かれているとします。これはこれで何も間違っていませんが、テスト設計ドキュメントに仕様概要として記載する場合などは次のようにしています。
- 入力値を保存したら、トーストで完了メッセージを表示する
少し分かりづらいので、対象・データに該当する部分を[]で、機能に該当する部分を<>で囲みます。
ここで、元の文章に含まれる "～を行う" は、動詞ではあるものの、「何を行うか」を機能として表現したいため、"～を保存する" に変えています。
- [入力値] を <保存し> たら、[トースト] で [完了メッセージ] を <表示する>
先に紹介した能動態・受動態の書き分けのために、機能を動詞で書くようにしているという理由もあるのですが、こうすることで、「～を保存したら」という部分に着目して「保存できなかったらどうなるのか？」や「保存するとき、他に何かすることはないのか？」というように思考を発散しやすくなります。
対象・データのFrom/To
対象・データについては、「どこの」（あるいは、「どこから」）・「どこへ」という情報をレベルを揃えて書くようにもしています。
例えば、設計ドキュメントに次のように書かれていたとします。
最新の商談情報を表示する
同じプロダクトの開発メンバーであれば暗黙的に伝わる文章ではありますが、テスト設計ドキュメントには次のように書きます。
- {連携するSFAの製品名} から取得した最新の商談情報を、
{開発するプロダクトの名前} の商談情報パネルに表示する
こうすることで、元の文章では暗黙的に読み取る必要があった「最新の商談情報」というデータについて、システムとしては「どこから、どこへ」、機能（表示する）としては「何を、どこへ」が明確になります。
こだわり その2：表現のバリエーションにこだわる
同じ対象に同じ表現（ワード）を使うことは、ドキュメンテーションにおいて大事なことです。
ただ、複数の条件を指定するときには、同じ表現を繰り返さないことが大切だと思っています。
例えば、
～の場合、～の場合、
～のとき、～のとき、
のような書き方はしないとしても、
～の場合に、～の場合は、
～のときで、～のときは、
のような書き方は意外とやりがちだったりします。
このため、自分の中で条件指定の際に使う表現のバリエーションをいくつか用意しておき、それぞれの表現で対象とする条件のレベルを揃えるようにしています。
具体的には、
・[曜日に関する条件] の場合、[時間に関する条件A] のときは、＊＊＊する
・[時間に関する条件B] の場合、[人数に関する条件] のときは、＊＊＊する
というような場合には、次のように表現のバリエーションを使って条件のレベルを揃えるようにします。
- [曜日に関する条件] の場合、
- [時間に関する条件A] のときは、＊＊＊する
- [時間に関する条件B] のときは、[人数に関する条件] であれば、＊＊＊する
こだわり その3：他に解釈の余地がない表現にこだわる
例えば、「～も」や「それ以外は～」など、何かを一括りにしたり、記載を省略したりする表現が使われている場合は、次のようなこと気を付けるようにしています。
- 「～も」に含まれる範囲は、他に解釈の余地はない？
- 「それ以外」に含まれるものは、本当に一括りにしてよい？
MECE（モレなく、ダブりなく）という言葉がありますが、文章で表現する場合、特にテスト設計ドキュメントにおいては、あえてダブらせて対比や差分を強調するようにしています。
これについては、あまり良い具体例が思いつかなかったのですが、
希望日が平日の午前中であれば、予約が必要
週末も同様
のような曖昧な表現がされていた場合、次のように曜日と時間をセットで明記するようにします。
- 希望日が平日の午前中であれば、予約が必要
- 希望日が土曜日・日曜日であれば、終日、予約が必要
さらには、次のように条件のレベルを揃えることで、対比がしやすく、差分が強調されるようにしたりします。
- 希望日が平日の場合は、午前中、予約が必要になる
- 希望日が土曜日・日曜日の場合は、終日、予約が必要になる
今回の例では、元の曖昧な表現からは読み取れなかった情報が新たに含まれています。
表現にこだわろうとすることで、実は不明確なまま読み手によって誤解や異なる解釈がされていたかもしれない部分を、誰もが同じ認識となるように揃えることができます。
まとめ
ということで、今回は私が日頃意識している日本語へのこだわりをご紹介しました。
はじめにでも書いた通り、これは『分かりやすい、読みやすい文章の書き方』ではありません。
実際、私が書くテスト設計ドキュメントにおいても、読みやすさを重視して、今回ご紹介した表現にしていないことがあります。
とはいえ、一度は脳内に思い浮かべたり、実際に文章として書き出してみたりするなどして、「バグの種になりそうなものがないか？」や「他に考えや解釈を広げられる余地がないか？」を考えるようにしています。
おまけの話
社内LT大会では、「こういうことを日頃考えているので、細かーい質問をしたりすることがあります。許してね！」みたいな感じで締めました。
後日、VPoEに「発表テーマ（「日本語へのこだわりのススメ」）を見たときは、これは技術発表なのか？と実は不安だった」と言われましたが、続けて「ちゃんと技術発表だった！内容もよかった！」と言ってもらえたのでよかったです。また、同僚からも大変好評だったので、今回ブログを書く上で大きく背中を押されました。
実はこういう技術系の社外発信するのは社会人歴2x年で初めてだったりします。
社内LT大会の登壇資料のテンプレートには「Next Action」を記載するフォーマットがあり、「Zennで簡単な記事を書くかもしれない」と書いたりしていたんですが、見事にイネーブルメントされました。（「やったことない」だけで「やりたくない」ではなかったので、機会をもらった上に背中も押してもらった形ですね。ありがたいことです。）
最後に、ナレッジワークでは、エンジニアを積極採用中です！
ご興味のある方はぜひお気軽にカジュアル面談に参加してみてください。
Discussion