日本語へのこだわりのススメ

ナレッジワークの社内技術共有会 Encraft Share Day(ESD)での発表資料です
@iinon（QAエンジニア）

Transcript

1. 日本語へのこだわりのススメ @iinon
2. © Knowledge Work Inc. はじめに 2 • 今日話す内容は、『分かりやすい、読みやすい文章の書き方』 ・・・ではありません！ • 普段　　がテスト設計をしているときなどに気にしていることのご紹介 です ◦ 設計ドキュメント（minispecやDesignDoc）を読むとき ◦ 設計ドキュメント（TestDesignDoc）を書くとき
3. © Knowledge Work Inc. なぜ日本語にこだわるのか？ 3 • 誤解や勘違いはバグの種になる ◦ 特にminispecやDesignDocで誤解や勘違いが生じると、 のちのち面倒なバグになる可能性が高い • 日本語にこだわると、 誤解や勘違いを防げる！あるいは、 気付くキッカケを得られる！ ・・・かもしれない
4. © Knowledge Work Inc. こだわり その１ 4 『主体』、『対象・データ』、『機能』の表現 に、こだわる
5. © Knowledge Work Inc. こだわり その１ 5 『主体』、『対象・データ』、『機能』の表現 に、こだわる 誰が 何を どうする
6. © Knowledge Work Inc. こだわり その１ 6 • 『主体』（誰が）を意識して、能動態 と 受動態 を書き分ける ◦ 例えば、 ▪ 必須項目が未入力の状態で 「保存」ボタンを押したら、アラートを表示する と、なりがちなところを ▪ 必須項目が未入力の状態で 「保存」ボタンが押されたら、アラートを表示する ▪ 必須項目が未入力の状態で 「保存」ボタンを押したら、アラートが表示される と、する
7. © Knowledge Work Inc. こだわり その１ 7 • 『主体』（誰が）を意識して、能動態 と 受動態 を書き分ける ◦ 例えば、 ▪ 必須項目が未入力の状態で 「更新」ボタンを押したら、アラートを表示する と、なりがちなところを ▪ 必須項目が未入力の状態で 「更新」ボタンが押されたら、アラートを表示する ▪ 必須項目が未入力の状態で 「更新」ボタンを押したら、アラートが表示される と、する ユーザーが主体 システムが主体 主体を システムで統一 主体を ユーザーで統一
8. © Knowledge Work Inc. こだわり その１ 8 • 『対象・データ』（何を）は 名詞 で、 『機能』（どうする）は 動詞 で書く ◦ 例えば、「更新」ボタンがクリックされたときの機能として、 ▪ 入力値の保存を行い、トーストで完了メッセージを表示 と、なりがちなところを ▪ 入力値を保存したら、トーストで完了メッセージを表示する と、する
9. © Knowledge Work Inc. こだわり その１ 9 • 『対象・データ』（何を）は 名詞 で、 『機能』（どうする）は 動詞 で書く ◦ 例えば、「更新」ボタンがクリックされたときの機能として、 ▪ 入力値の保存を行い、トーストで完了メッセージを表示 と、なりがちなところを ▪ 入力値を保存したら、トーストで完了メッセージを表示する と、する 『機能』が明確になる 他のケースを意識しやすくなる
10. © Knowledge Work Inc. こだわり その１ 10 • 『対象・データ』（何を）は、 どこの（どこから）・どこへ を レベルを揃えて 書く ◦ 例えば、 ▪ 最新の商談情報を表示する と、なりがちなところを ▪ {連携するSFAの製品名} から取得した最新の商談情報を、 {開発するプロダクトの名前} の商談情報パネルに表示する と、する
11. © Knowledge Work Inc. こだわり その１ 11 • 『対象・データ』（何を）は、 どこの（どこから）・どこへ を レベルを揃えて 書く ◦ 例えば、 ▪ 最新の商談情報を表示する と、なりがちなところを ▪ {連携するSFAの製品名} から取得した最新の商談情報を、 {開発するプロダクトの名前} の商談情報パネルに表示する と、する 『対象・データ』の所在が明確になる 「どこから、どこへ」「何を、どこへ」が明確になる
12. © Knowledge Work Inc. こだわり その２ 12 表現のバリエーション に、こだわる
13. © Knowledge Work Inc. こだわり その２ 13 同じ対象に同じ表現（ワード）を使うのは、大事 ただ、 複数の条件を指定するときは、同じ表現を繰り返さないことが、大事 だと、　 は思っている
14. © Knowledge Work Inc. こだわり その２ 14 • 同じ表現の繰り返し、 ◦ ～の場合、～の場合、 ◦ ～のとき、～のとき、 は、ないとしても、 ◦ ～の場合に、～の場合は、 ◦ ～のときで、～のときは、 となると、意外とやりがち • ではなく、 ◦ ～の場合 ◦ ～のとき ◦ ～であれば のように、違う表現を使う • それぞれの表現で 対象とする条件のレベルを揃える ＋
15. © Knowledge Work Inc. こだわり その２ 15 • 例えば、 ◦ [曜日に関する条件] の場合、[時間に関する条件A] のときは、＊＊＊する ◦ [時間に関する条件B] の場合、[人数に関する条件] のときは、＊＊＊する と、なりがちなところを ◦ [曜日に関する条件] の場合、 ▪ [時間に関する条件A] のときは、＊＊＊する ▪ [時間に関する条件B] のときは、[人数に関する条件] であれば、＊＊＊する のようにする
16. © Knowledge Work Inc. こだわり その２ 16 • 例えば、 ◦ [曜日に関する条件] の場合、[時間に関する条件A] のときは、＊＊＊する ◦ [時間に関する条件B] の場合、[人数に関する条件] のときは、＊＊＊する と、なりがちなところを ◦ [曜日に関する条件] の場合、 ▪ [時間に関する条件A] のときは、＊＊＊する ▪ [時間に関する条件B] のときは、[人数に関する条件] であれば、＊＊＊する のようにする
17. © Knowledge Work Inc. こだわり その３ 17 他に解釈の余地がない表現 に、こだわる
18. © Knowledge Work Inc. こだわり その３ 18 • 「～も」とか「それ以外は～」などは要注意 ◦ 「～も」に含まれる範囲は、他に解釈の余地はない？ ◦ 「それ以外」は、本当に一括りにしてよい？ • MECE（モレなく、ダブりなく）という言葉があるが、 文章で表現する場合は、あえてダブらせて対比や差分を強調 する
19. © Knowledge Work Inc. こだわり その３ 19 • 例えば、 ◦ 希望日が平日の午前中であれば、予約が必要 ◦ 週末も同様 のような書き方がされている場合、 ◦ 希望日が平日の午前中であれば、予約が必要 ◦ 希望日が土曜日・日曜日であれば、終日、予約が必要 のようにする さらに、 ◦ 希望日が平日の場合は、午前中、予約が必要になる ◦ 希望日が土曜日・日曜日の場合は、終日、予約が必要になる のようになっていると、なお良し
20. © Knowledge Work Inc. まとめ 20 • 今回は、　 が日頃意識している日本語へのこだわりをご紹介しました • 実際の成果物では、読みやすさを重視して 今まで話してきたような表現にしていない場合も多いです が、 • 一度は脳内に思い浮かべてみたり、実際にテキストにしてみたりして、 ◦ バグの種になりそうなものがないか？ ◦ 他に考えや解釈を広げられる余地はないか？ を確認するようにしています