1. オフショア開発におけるドキュメンテーションとは？
ドキュメンテーションについての概要と種類についてご紹介します。
1-1. ドキュメンテーションとは？
システムを開発する際に完成したイメージを記載した資料、完成したシステムの使用方法を記載した取扱説明書などが、システム開発におけるドキュメンテーションです。
ドキュメンテーションを作成するメリットとしては、国内外の開発者同士のコミュニケーションミスを防げる点、システムに不具合が発生した場合に対処がしやすい点、納品後の適切なシステム運用の役に立つ点があげられます。
ただし、オフショア開発でのドキュメンテーション作成には課題もあります。依頼先の国外の開発者へ適切に情報を伝えるために、分かりやすい資料を作成する必要がある点や、仕様変更があるたびにドキュメンテーションの内容も訂正をしなければならない点があります。
また、担当者が開発業務に追われてドキュメンテーションの改訂が後回しになり、現場の進捗に合わせたドキュメンテーションのアップデートができなくなる点もあります。
最新のドキュメントがなければ、トラブルが発生した時に一から原因を探さなくてはならないため、開発に大きなタイムロスを生じさせる恐れがあります。
1-2. ドキュメンテーションの種類
ドキュメンテーションの種類は、要件定義書・基本設計書・詳細設計書・コーディング/単体テストと主に4種類に分けられます。
■ 要件定義書
要件定義書とは、開発するシステムに関する情報をまとめて、発注者側に開発するシステムの概要を把握してもらうための書類です。要件定義書は依頼を受けた開発者（受注者）が作成するのが一般的で、依頼した内容と開発する内容に違いがないか、双方が確認できるように作成します。
認識のズレが生じないよう、実装する機能を詳細に記載するとともに、専門知識がない人が見ても分かるよう、文章の言い回しや表現には注意する必要があります。
■ 基本設計書
基本設計書とは、要件定義書で定めた機能を、具体的にどのように形にするのかを設計した書類です。設計書には基本設計書と詳細設計書の2種類がありますが、基本設計書は依頼側と開発側で共通の理解を得ること、詳細設計書は開発側と現場で情報を共有することが目的です。
基本設計書では、開発する機能の実装方法を細かくまとめ、図解などで視覚的に分かるよう工夫すると品質の高い設計書に仕上がります。ユーザーが直接目で見て触れる部分を設計するのも、基本設計書の役割の一つです。
次の段階である詳細設計書では、ユーザーの目に触れない内部までの設計をおこないます。基本設計書に記載する内容は、作業手順を示す業務フロー、作成すべきシステムの機能一覧、画面や帳票のレイアウト設計、データベース作成時の規則やデータの定義などがあります。
■ 詳細設計書
詳細設計書とは、基本設計書で記載したシステムの大枠を、具体的なプログラムに落とし込むための書類です。
詳細設計書を作成する際はオリジナルの書き方をするより、既存のフォーマットに習いながら作成することで、情報を上手く整理し作業者が理解しやすい書類に仕上げることがポイントです。目的に応じてクラス図、パッケージ図、シーケンス図などを使い分けます。
■ コーディング/単体テスト
詳細設計をもとにコーディングでシステムの構築をおこない、プログラムの完成ごとにテストを実施します。テストには実施項目や規則があり、同じ基準でテストできるよう書類にまとめます。単体テスト仕様書はプログラム一つひとつのテスト方法を記載する書類で、記載通りに検証をおこない成績を記録します。
統合テスト仕様書は複数のプログラムを繋いだ際にシステムが機能するかを検証するための書類で、項目ごとにテストで得られた成績を記録します。システムテスト仕様書はシステム全体を繋いで機能するかを検証する書類です。テスト関連の他にも、クライアントに使用方法を伝えるための手順書として運用マニュアルも合わせて作成します。
2. オフショア開発におけるドキュメンテーションの重要性
オフショア開発でドキュメントが必要になるシーンは、発注側と開発側の情報共有、開発中の業務の引き継ぎ、納品後の保守や運用です。情報共有については、ドキュメンテーションがあることでシステムの完成イメージを詳細にシェアできますし、予算作成や業務の分担などにも利用可能です。
開発が始まれば、複数の担当が工程ごとに開発を進めるため、業務の引き継ぎが発生します。漏れなく効率的に業務状況を共有するために、ドキュメンテーションを活用します。システムの運用開始後に、ドキュメントがあれば担当者の移動や退職があっても全体の流れを把握しやすくなります。
3. オフショア開発におけるドキュメンテーション作成のポイント
発注側と開発側、開発者同士のコミュニケーションを円滑にするために、効果的なドキュメンテーションの作成ポイントを解説します。
3-1. ドキュメントの言語について
海外とのやりとりが必要になるオフショア開発において、ドキュメントの言語をどうするかははじめに決断する必要があります。世界の共通言語である英語でドキュメントを作成するのが一般的ではありますが、日本語で作成したドキュメントを現地の言葉に翻訳する方法もあります。
ただし、ドキュメントをひとつずつ翻訳するのには時間と手間がかかり、翻訳する際にニュアンスが変わってしまい、意思疎通が難しくなる恐れもあります。分かりやすい英語でドキュメントを作成すれば、両者の認識のズレを抑えられるはずです。
3-2. 翻訳の用語の統一
ドキュメントで使用する言語について、大部分を英語で作成するのが一般的ではありますが、ドキュメントの内容によっては、簡単な英語だけでは伝えきれない箇所もでてきます。業務内容が細かく英語での作成が難しい場合は、内容にズレがないか注意しながら、現地語に翻訳するのも一つの手段です。
もちろん、翻訳する人によって使う言葉が変わるとトラブルの元になるため、多様する専門用語などがあれば、ルールを設けて翻訳の仕方を統一する必要があります。現地の言葉で書かれていれば、開発スタッフの負担軽減になるため、お互いの仕事のしやすさにもつながります。
3-3. 曖昧な表現はせず言い切り表現を使う
日本人はものごとを曖昧な表現で伝えることに慣れており、聞き手も相手の言いたいことを察知して業務を進めるのが習慣化しています。お互いそれが当たり前であるため、日本人同士では大きなトラブルになりません。
しかし、海外の人は察知しながら仕事を進めることはしないため、オフショア開発の際は注意する必要があります。
よくあるトラブルの例としては、開発スタッフが言われたこと以下しかしないため、仕事が一向に進まない、言われていないことは自己判断で進めていくため、気づいたときには間違った方向で仕事が進んでいた、というケースが多くあります。
日本と同じ感覚で仕事をしてしまうと、日本ではあり得ないと思うようなことが起きてしまうのです。
日本の進め方をわかってもらうのも手段のひとつですが、相手の習慣を矯正するのは手間がかかるため、業務をスムーズに進めるには相手に合わせた指示をした方が早く済むことがほとんどです。相手がやるべきことを明確に理解できるよう、指示をする際は曖昧な表現をせず、言い切り表現を心がけることが大切です。
3-4. プロジェクトの対比用語集を用意する
はじめてのオフショア開発や前回のオフショア開発から期間が空いている場合、コミュニケーションの中に聞き慣れない言葉があると戸惑うかもしれません。日常的なやりとりでつまずいてしまうと、本題に入るまでに時間のロスが発生します。
小さなロスでも日常的に蓄積されていくとプロジェクト全体の遅延につながる恐れがあります。プロジェクトに関連する用語については、日本語・英語・現地語で対比用語集を用意しておくと、円滑なコミュニケーションの助けになるはずです。
3-5. ドキュメントスタンダードの作成共有する
ドキュメントを作成する際は、内容の統一性を保ちながら開発手順の規定を進めるために、ドキュメントスタンダードを作成・共有することが重要です。業務が個人の能力に依存するようになると、成果物の品質にバラつきが出てしまう恐れがあります。
ドキュメントスタンダードに沿って開発を進めることで、誰でも一定のレベルでの開発ができるようになるため、品質のバラつきをおさえる効果を期待できます。スタンダード化するものは開発に関わる全ての工程が対象で、コーディング規約やプログラム規則、記録方法などに対してもルールを設けましょう。
ドキュメントを作る際は、誰が使うものかを意識して作成すると、形式的な書類ではなく、仕事の効率化を助けるツールに仕上げることができます。
3-6. 図・表を交えた説明にする
大量のドキュメントがテキストだけで構成されている場合、すべてを読み込むのに負担がかかります。見やすい文章に仕上げるための工夫として箇条書きがありますが、効果には限界があるため、図・表を交えて説明するようにします。
図・表を用いて視覚的に示すことで、スムーズな理解につながるからです。指示内容が分かりやすいと読み手の印象も良くなるため、今後のコミュニケーションもしやすくなるはずです。ひと手間を加えることで、結果的に業務の効率化が図れるため視覚的なアプローチはおすすめです。
3-7. 画面遷移図・画面定義書を使う
画面遷移図とは、画面を操作したときの変化を視覚的に表した書類のことで、画面定義書とは、システムを操作したときに表示される画面のレイアウトを記載する書類のことを指しています。画面遷移図や画面定義書を作成することで、関係者が全体像を把握するのに役立ち、システムに必要な画面の洗い出しにも活用できます。
また、作成する画面ごとの関係性の確認も一目で分かるため作業がしやすくなりますし、見積りも出しやすいメリットがあります。特に開発したシステムを一般向けに公開する場合、視覚的な分かりやすさは重要項目のひとつであるため、画面遷移図の作成は欠かせません。
3-8. 表現レベルのバラつき防止のための目次や記述サンプルの作成
ドキュメントの作成は業務の担当ごとに複数人でおこなうケースもあるため、人によって表現レベルのバラつきがあると、読み手が混乱してしまう恐れがあります。表現レベルのバラつきを軽減するために、ドキュメントの分量が多くなるようであれば項目ごとに目次を設定するのがおすすめです。
また、複数人が同時にドキュメントを作成しても記載内容の統一性が保たれるよう、記述サンプルの作成も欠かせません。我流の書き方をさせない工夫が、クオリティの高いドキュメント作成には重要です。
3-9. インプット・アウトプット・プロセスの意識をして作成する
一般的な開発の流れは、要件定義・設計・開発・テスト・導入の順に工程をステップで進めます。ウォーターフォール型とも表現されますが、ある工程が完了してから次の工程に突入すると、基本的には後戻りして開発することはありません。
前工程でアウトプットされた成果物は、そのまま次の工程でインプットに変化するため、全体の流れ（プロセス）を見据えたドキュメント作成が求められます。オフショア開発においては、最終的なゴールを目指すための大きな流れと目の前の必要な業務が同時に把握できると、円滑な開発につながります。
3-10. 一定水準品質のドキュメント作成を目指す
オフショア開発では、複数の業務担当者がひとつのドキュメント作成に携わるケースが多々あります。人によっては他の業務と重なりドキュメント作成に割ける時間がない、仕様変更にともない関連ドキュメントが何度も改訂されると、ドキュメントの品質にバラつきが生まれます。
ドキュメント品質がバラついていると、業務の進行のさまたげになる恐れがあるため、一定水準の品質を保つ必要があります。
品質を落とさないよう心がけて作成を進めても、1,000ページを超えるようなドキュメント作成になる場合、物理的に品質を落とさざるを得ないこともあります。
その場合、ドキュメント作成を外注することで、作業担当者の負担を軽減させることも可能です。優先順位を考え従業員を開発業務に専念させたい場合、外部の助けを借りるのも一つの手段となります。
3-11. 日本独自の商習慣の理解を共有する
オフショア開発では、文化や習慣の違う人々と仕事を進めるため、はじめはお互いが業務をしやすいように歩み寄る必要があります。しかし、日本からの業務を受注し続けてもらうためには、日本のビジネスの進め方を理解し、慣れてもらう必要があります。特に納期を見据えた逆算思考については、ぜひ共有したい考え方の一つのはずです。
なぜ日本の商習慣を知る必要があるのか、どのように動けば日本の会社とうまくやっていけるのか、丁寧に伝えていくことが大切です。いつまでも歩み寄るだけでいると甘えが生じてしまうため、メリハリのある業務をするためにも、教育の観点からのアプローチも欠かせません。
3-12. ドキュメントレビューの機会を設ける
設定したルールや規則にしたがってドキュメント作成をおこないますが、規則通りに作成がおこなわれているか、ドキュメントレビューの機会を設けて定期的に確認しましょう。人が作るものであれば、ミスや漏れは必ず出てきてしまうため、作成者とは別の人がレビューをする必要があります。
レビューの流れとしては、記載情報の誤りをチェックする校閲、誤字・脱字などをチェックする校正、文章の練り直しをおこなう推敲の順におこないます。近年では自動校正が可能なツールの使用も増えているため、手間のかかる作業は効率的に進めていくのがおすすめです。
3-13. ドキュメントのプロセス確立と遵守
ドキュメントを作成する際は、記事内でご紹介した翻訳ルールの設定、理解を促進するための工夫の実施、作成規則の設定や品質確保のためのレビューなど、すべてを盛り込むことではじめて有効なドキュメントとして機能します。
ドキュメントがしっかりと作り込まれていれば、開発プロセスの効率化や開発期間の短縮につながりますが、ドキュメントの品質が低いと逆効果になるリスクもあります。
特に現場レベルではドキュメントが軽視されがちになり、トラブルの元にもなりかねません。ドキュメント作成プロセスをしっかりと確立し、規則を遵守して作成に取り組む姿勢が大切です。
4. まとめ
オフショア開発におけるドキュメンテーションは、文化や習慣の違うもの同士のコミュニケーションを円滑にし、かつ開発プロセスを効率的に進めるサポートの役割を担っています。一方でドキュメントの品質が保たれていないと、効率的に進めるどころかトラブルを発生させて遅延を引き起こすリスクも抱えています。
ドキュメントが本来の役割を果たせるよう、記事内でご紹介したポイントをおさえて作成に取り組んでみてください。
「オルグローラボ」では、ベトナムのオフショア開発事業をサポートしています。オルグローラボを利用すれば、業務スタートまでのプロセスを省略でき、納品後の保守運用までサポートしています。特にベトナムは上述したとおり、低価格で高品質な業務を依頼でき、国民性も良いのでおすすめです。
