ネイティブゲームディレクター時代に書いていたドキュメントリスト


# 結論
プロジェクトにとってのドキュメントは、プログラムにとってのテストコードと同じ。

ドキュメントをないがしろにして大規模なものをつくると破綻し、運用をすすめるほど負債が溜まるので、ちゃんと目的にそったドキュメントを書いて、保守していったほうがみんな幸せ。

# はじめに
ソーシャルゲーム会社でディレクター(ゲームデザイナー)として働いていた当時、ドキュメントの作り方が会社で統一されておらず、そもそも「動いているものが仕様書」という時代。

いろいろ試行錯誤しながらドキュメントを作成し、関係者から「仕事がすすめやすい」と言われていたので、どのようなドキュメントをどのように作っていたのかをまとめる。


もともとコンシューマゲームの会社だったり、海外展開しているゲーム会社は、もっとちゃんとドキュメントの種類をまとめていると思う。

# ドキュメントかの概要図
下の黄色い部分は、どんな役割の人が利用するのかをわかりやすくするため書いてある。

![docs.png](https://qiita-image-store.s3.amazonaws.com/0/14275/43fe3d2b-dc7b-1734-04de-a4738b6468b5.png "docs.png")


# 例)定期的に行うイベントを考えた場合のドキュメント

## 2ページャー
- イベントの面白さを伝えるドキュメント。やるやらをここで判断
- 名前のとおり2ページくらいでつくる
- 記載する内容は以下のとおり
	- 画面イメージ
	- ターゲット
	- 何が面白いのか

## 10ページャー
- イベントの概要を伝えるドキュメント
- 10ページでなくてもいい
- 記載する内容
	- 世界観
	- 施策の目的
	- コアループ
	- 画面イメージ
	- リソースの流れ ※[マキネーション](https://www.youtube.com/watch?v=PsqaG_GLmvw)っぽい書式で書いてた
- 開発チーム用と、プロモーション用で別になることもある

## GDD (ゲームデザインドキュメント)
- 2pager/10pagerに書いたこと
- KGI / KPI
- テキストでの仕様
	- 定数/変数になるべきものは、[]で囲うなど、書式を分ける
- 画面/処理フロー図
	- 画面アウトライン
		- 画面については、オブジェクトの大体の配置と文言を記載
	- アニメーションが入る場合
		- 細かく指定したいアニメーションは、絵コンテをつくる
	- 処理フロー図
		- エラーの分岐も忘れず記載 (以下は例)
			- データがない場合
			- 制限時間がある場合、バトル中に制限時間をオーバした場合
			- バトル中にイベントの終了時間を過ぎた場合
- ログの設定
	- どのタイミングでログを取りたいか
	- 目的はなにか
- ざっくりのテーブル構成
	- ここは運用中に変更したい、というものは事前にテーブル構造を作成し、オンラインで変更できるようにする
	- 何が指定できればいいのかを明確にする
- 拡張機能(アップデートでの投入など)として入れたいもの
	- 入れることが確定しているものはモチロン、入れたいと思っているという程度のものも書いておく

## LDD (レベルデザインドキュメント)
### マップ情報など
- マップを移動するゲームは作ったことがないので割愛

### 数値計算
- 大体どこもexcelを利用する。
- 基本的には数値のみを扱う
- ディレクター業の中では一番楽しい作業(だった)
- 複数回やるイベントであることがわかっている場合は、過去のログデータなどから数値を計算できるようにする
	- 初回はすでにあるログデータから数値を作成

### リソース管理ファイル
- リソース管理ファイルはLDDではないけど、とりあえず入れとく
- 必要な画像データの管理
- ボイス/ジングル/SE(サウンドエフェクト)/BGM の管理

## デバッグ用ドキュメント

### テスト仕様書 (エンジニア/QA用)
- 正常系 / 異常系 / 不正目的 などの観点から作成する
	- 正常系 : 想定しているとおりの遊び方
	- 異常系 : たとえばユーザ名が空文字列だとか
	- 不正目的 : ボタン連打、多端末で同時に操作 など
- 確率に関するものは超重要

### デバッグツール仕様書 (エンジニア用)
- 画面仕様書などはなくてもよい、文字ベースで伝える
	- 敵キャラを指定して、そのキャラのHPを残り1にする etc

### デバッグツールの利用方法 (QA用)
- 必ず画面つきで説明する
- デバッグ画面の出し方
- 利用できるデバッグ機能のざっくり説明
- 今回のデバッグツール使用例

## 運用ドキュメント
### ディレクター用ドキュメント
- 運用フェーズに入った場合、何を、いつ、どのようにやればいいかをまとめる
	- 各フェーズの開始時期 (リリース1か月前 など)
	- レベルデザイナーが毎月設定する値
	- どの数値を指標として見るとよいか、またその基準値
	- 毎月用意するリソース数
		- 画像 (キャラ/バナー)
		- 文章 (キャラ/お知らせ/通知文言)

### CS用ドキュメント
- 問い合わせ用ページの利用方法
- データの確認方法と、そのページにたどり着くまでの方法


# ドキュメントを書くことのメリット/デメリット
## メリット
### 色々な人に感謝される
- ドキュメントが用意されていることが珍しい環境の場合は効果大
- 特にQAさんからは、超絶感謝される → 仲良くなる → 細かい改善案をもらえる → 品質が高くなる という、いい関係を結べる

### ほったらかせる
- ドキュメントが整備されていると、質問する前に「ドキュメントに書いてあるかも」と考えてもらえる → ドキュメントに書いてあるかどうかよくわからないから聞こう、が減る
- ドキュメントに記載済みの場合、ドキュメントのリンク投げて、「Xページに書いてありますよ」と伝える
- ドキュメントに記載していない場合、「それはドキュメントにないので、直接説明に行きます。」→「できれば、このドキュメントに追記しておいてもらえると助かります」と言うと、たいていやってもらえる

## デメリット
### 最初に時間がかかる
- ただでさえ企画が動かなければ、他の人が動けないのでドキュメントを整備する暇がないというのはありえそう
- 自分の場合は、よほどのことがなければ、他の作業は断ってドキュメントを書いていた


### 仕様を決めきらないうちに作ると、メンテナンスコストが高い
- この段階でドキュメントを作ると、ドキュメントを最新の状態に保つのが難しい
	- 色々な人の利権が交わる場合などは、特にちゃぶ台返しが決まりがち
- そのために2pager, 10pagerでめちゃくちゃ議論するんだけど、そういうのをなかったことにしてしまう人がいるのも事実

### ドキュメントを読んだ人が、単なる作業者になってしまう
- ドキュメントをしっかり書くと「こうしたほうがいいんじゃないか」というのがメンバーから出てきにくい気がする
- 自分が得意ではないところは、「要相談」「もっといい案あれば教えて」とか書いておくと、多少改善した

# まとめ
ゲーム会社での事例を書いたけど、システムのドキュメントも同じような思想で作っている。
誰にとって、どんなものがあると助かるか、という目線で考えると、必要なドキュメントを取捨選択できる。