SEをしているとQA表、あるいは課題管理表を見たことのある人が少なからずいると思います。質問事項、回答、Open/Closeが書かれたExcelのアレです。
そのQA表へ「質問事項を追記しといて」と若手社員に依頼したら、「どう書けば良いですか？」という返事を1日後にされました*1。思い返してみると、若手の頃はQAを書いては先輩に見てもらい、ダメ出しと書き直しを繰り返した記憶があります。
そんな反省を踏まえ、QA表への質問の書き方をまとめます。初めてQAを書くシステムエンジニア向けの記事です。
質問文のフォーマット
QA箇所を明示する
何の資料・情報に対する質問かを最初に明示した方が良いです。質問者と回答者の間で質問内容の認識を合わせやすいです。凝ったQA表では資料の名前を書く列があったりします。
例えばAPIの項目について質問するのであれば、最初に下記のような前提を書きます。
Hoge_API定義書.xlsx # [登録API]シート 項目名 : orderId
最初に質問を書く
はてな（？）で終わる文書を最初に書きます。背景・理由を述べる場合はその後に続けて書きます。
質問を先に書くことにより、その質問の要点と優先度がすぐに分かるようになります。後にQAを検索するときもすばやく検索できるようになります。
Hoge_API定義書.xlsx # [登録API]シート 項目名 : orderId 桁数は何桁でしょうか？ （lengthがブランクです）
1行1質問を意識して書く
QA表の1行には1つの質問・回答が原則です。質問の趣旨が異なる場合は行を分けて書きます。
1行に複数の質問を書いた場合、1つの質問が回答できないためにQAがCloseされないという状態が続きます。
Hoge_API定義書.xlsx # [登録API]シート 項目名 : orderId、customerId 質問1. orderIdの桁数は何桁でしょうか？ 質問2. customerIdの型は何でしょうか？
上のように2つの質問を1つにまとめて書いた場合、質問1はすぐに回答され、質問2はなかなか回答されないという状況があります。また、質問1と2を合わせて回答しようとして両方とも回答待ちになる状況もあります。多少冗長であっても、回答状況の把握のしやすさを優先して、質問1と質問2は分けて書きます。
Hoge_API定義書.xlsx # [登録API]シート 項目名 : orderId 桁数は何桁でしょうか？
Hoge_API定義書.xlsx # [登録API]シート 項目名 : customerId 型は何でしょうか？
漏れなく書く
影響範囲が分かっているのであれば、その影響範囲を明示すると有効な場合があります。1行1質問が原則ですが、趣旨が同じであればまとめて書くことでQAのやりとり回数を少なくできます。
例えばAPIの項目は横断的に使用されることも多いので、把握できている箇所を列挙します。
Hoge_API定義書.xlsx # [登録API]シート 項目名 : orderId 桁数は何桁でしょうか？ また、当項目は同資料の下記シートにも定義されています。 下記シートのorderIdの桁数も合わせてご回答お願いいたします。 [更新API]シート [削除API]シート
このように記述することで確認漏れを防ぐことができます。また、登録APIのorderIdと、他のAPIのorderIdの桁数が同じであるかどうかの確証も得られます。（過去に、項目名が同じなのにスペックが違って悲惨な目にあった経験があります*2）
質問先に応じた質問の書き方
質問先は、お客さん（クライアント）であったり、他システムの開発担当者であったりと様々なケースがあります。クライアントに対しては「どうすべきか？」を、他システムの開発担当者に対しては「どうなっているか？」を尋ねる質問が多いと感じています。質問先に合わせて質問の文書を変更します。
用語を使い分ける
自社で使用している用語と質問先が使用している用語が同じであるとは限らないです。用語によって認識のずれがないように、質問先が使用している用語で質問を書きます。
例えば「orderId」はエンジニア間では通じますが、クライアントからするとそれに該当する用語は「注文番号」であったりします。クライアントに質問するときは「注文番号」という用語を使うようにします。
決定の余地を残す（クライアント向け）
クライアントに対しては決定の余地を残す質問をします。「注文番号の桁数は16桁でしょうか？」ではなく「注文番号の桁数は何桁でしょうか？」というような質問です。回答を制限しないオープンクエッションに近しいです。
先入観で語りますが、雇用者を「パートナー」ではなく「自分より下」と考えているクライアントが多いと思っています。自分の考えを押し付けるような質問は波が立ちかねないので、クライアント自身が意思を持って回答できるような質問を書きます。
システムに詳しくないクライアントに対して技術寄りの質問をする場合は案を書いて選択してもらうようにします。その案に対して理由や利点・欠点を記述できると良いです。（過去にオープンクエッションをして回答に2ヶ月かかった経験があります*3）
Hoge_要件定義書.docs # 受注処理 項目名 : 注文番号 桁数は何桁でしょうか？ 下記の2案が考えられますが、どちらを採用すれば良いか、ご回答をお願いします。 案1. 16桁 現行システムでは注文番号を16桁で処理しています。 互換性を考慮した場合、16桁で処理する方針がよいと考えます。 案2. 20桁 注文番号で連携元を判別したいという要件があります。 この要件を考慮した場合、「連携元情報（4桁）＋現行の注文番号」とする案が考えられます。
回答方法を明確にする（他システムの開発担当者向け）
他システムの開発担当者に対しては出来るだけ回答方法を明確にした質問をします。「orderIdのスペックを教えてください」ではなく「orderIdの桁数、型、フォーマット（最大値：最小値）をご教示ください」というような質問です。
回答の仕方が決まっていた方が答えやすいです。「スペックを教えてください」だと回答者が桁数と型だけを答えれば良いか、もしくはフォーマットまで答えた方が良いか悩みます。悩む分、回答を得られるまで時間がかかります。
また、フォーマットまで知りたいのに桁数と型だけが回答された場合、フォーマットが何かを追加で質問することになります。QAのやりとりを最小限にするためにも期待の回答方法まで書いた質問が良いです。
まとめ
QA表への質問の書き方をノウハウを交えてまとめました。多少なり参考になればと思います。
