今回は、品質高く手間をかけずにエンジニアに伝えるためのドキュメント作成のポイントについてお話したいと思います。
オフショアを開始された際に悩むのが資料作成です。日本にいると海外と開発の仕事をする機会が非常に少なく、自分の意思を海外のエンジニアにどのように書いたら伝わるのか、という所に非常につまづかれることが多く見受けられます。これは、開発現場のみならず、一般の業務および生活にも当てはまる事となります。
これまで数十社のお客様のご相談を受け、その経験より共通している事は以下の3つとなります。
・何をどこまで書けば伝わるか
・何をどう書いたら伝わるのか
・何と書いたら伝わるのか
というところで、オフショア開発においては特に日本国内とは違ったドキュメント作成ノウハウが必要となってくるのですがまとまった資料等が有るわけでもないため各社色々工夫を凝らされているので実態です。
そこで今回は、私が紹介している典型的なオフショア向け資料作成方法を紹介させて頂きます。（※各社様毎に開発特性が異なる為、適用する際には改変していただくとより、運用が回りやすいかと思います）
まず、マインドセットとして「いきなり100点を目指さない」
①一気に依頼したい事柄を書く
誤解や誤読を恐れて詳細に書く時間を沢山使うより誤解や誤読が一定あることを覚悟し、依頼したい事柄を一気に書いてしまいます。
※この時は、整理されていなくてもOK
②記載事項の整理
しかし、誤解、誤読で依頼事項に対して作り直しになったら元も子もありません。ここで、一気に書いたものを整形していきます。
次に整理整形について考えるべきは「自由度をコントロールする」
もちろんですが、エンジニアに要件だけを丸投げして提案を期待するというスタンスで依頼すると100％、炎上します。（以前それをやって綺麗に燃えてしまいました・・）
何をエンジニアに任せ、何をこちらで指定するかの線引が必要です。
私のこれまでの経験上、大きな問題を抑える為に、以下の3点を気をつけています。
・インプットは何か？・・・インポートされるファイル、読み込みするDB、ユーザーから入力されるデータ、他システムから連携されるデータ
・プロセスは何か？・・インプットを元にどんなロジックでデータを作るか
・アウトプットは何か？・・どんなアウトプットが出るか。ファイルなのかデータベースへの保存なのか、画面遷移なのかetc.
そして最後にこれらをデータフローダイアグラム（DFD）で表現してあげると思い違いが減らせる資料が出来上がります。非常に簡素ですが、こんな感じです。
例）ログイン機能
＃インプット [ユーザー入力情報] キーボードよりユーザ情報を画面に入力
↓
＃プロセス [ログインプロセス] 入力されたユーザ情報のシステム内存在確認
↓
＃アウトプット [ログイン後画面] システムの操作画面の表示
これだけだと情報少ない為、別のシートにユーザー入力情報の詳細、ログインプロセスのロジック（正常系/異常系）、ログイン後の画面URLなどをまとめます。ここまで出来たら、整理を行いエンジニアへと依頼します。
インプット、プロセス、アウトプットが押さえられているので、自分の理解で作ろうとしても、コードが汚いくらいとなります。これは、コード規約など書き方ルールで補っていきます。慣れてくると、1人月くらいのシステムのボリュームであれば30分〜1時間ほどで、この程度の指示書まで作ることが出来ます。
もっと詳細が知りたい！ということでしたら、是非エボラブルアジアまでお問い合わせくださいませ。
他にも聞きたいこと等ございましたら、お気軽にご連絡くださいませ。
それでは。