エンジニアが問題を説明する時に気を付ける事

コンテンツデザイン部の金井と申します。今回は、分かり易い説明をする為に心掛けている事を書いていきます。

結論

読む人のリソースを少なくするように心掛ける。
その為に、

• 結論から先に言う
  • 何を要求しているのかが一目で分かる
  • 読み返す際も、全てを読む必要がなくなる
• 長文で纏めず、要点を切り分けて説明する
  • 文章を読者に噛み砕かせる手間を極力省く
  • 文章としての体は重視せずに、箇条書きや強調を駆使する
  • フォーマットがあれば、それに従えば知識などなくてもある程度分かりやすく記述出来る
• 専門用語は必要に応じて噛み砕く
  • 読者が何に長けていて、何に疎いのかを想像する

悪い例

お疲れ様です。
先日より発生している、お勧めユーザーを検索するAPIで長い時間が掛かってしまう問題に関してですが、ユーザーデータの量が想定より多く、またそれに対してデータベースのインデックスが適切に張られていなかった事が原因でした。
また、現在業者によるリセマラアカウントが日々増加している事も鑑みると、インデックスを適切に張り直しても現在の仕様ではその内また時間が掛かるようになってしまう事が想定される為、お勧めユーザーの検索ロジックの変更をしたいと考えています。
現状のお勧めユーザー検索ロジックの問題となっている部分は、3日以内にログインしている、という条件が現状のDAUから考慮すると多過ぎる点と、また、その他の絞り込む条件もその莫大なユーザー数からの抽出には時間が掛かってしまう点です。
その為、3日以内にログインしている、という条件を、直近にログインをしたユーザーの指定数に変更し、その中から抽出するという形にしたいです。
これに変更しても直近に遊んでいる人からお勧めユーザーを参照したいという要望は変わらないまま、DAUに関わらず参照量は一定になりますので、APIで掛かる時間も一定になるからです。欠点を挙げるとするのならば、ゲームが遊ばれなくなる時間帯などには同じユーザーが参照されてしまう可能性が高いという事がありますが、現状の盛況振りから考えるとこれから先も基本無く、またあったとしてもそう強い問題でもないと思いますので、一考願いたいです。
よろしくお願いします。

どこが悪いのか？

順序立てて説明していますが、読むのに疲れますし、最後まで読まないと何をどうしたいのか分かりません。
と言うより……読もうと思えないですよね、これ。
まあ……この文章を総括してしまえば、エンジニアの自己満足です。

エンジニアは問題の原因究明、解決に100%のエネルギーを注いで対応しているかもしれませんが、
プランナーやプロジェクトマネージャー、ディレクターといった、仕様を考える人、最終的に判断を下す人達はもっと色々な事を同時並行でやっていたりします。
要するに、上に立つ人はエンジニアと同じだけのエネルギーを原因解決だけに注いでいられない訳です。
エンジニアから欲しいのは主に、どのような問題が発生し、その解決に必要な事柄は何なのか？　という事です。
そういう事を留意した上で、タスクが多い人のリソースをエンジニアと同等レベルに食わせない事を考えましょう。
その為にすべき事としては、以下になります。

• 結論から先に言う
• 要点を分かりやすくする
• 専門用語は必要に応じて噛み砕く

現状の個人として強く意識している考えなので、もっと考えるべき事柄や無意識に行っている事柄もあると思いますが、ひとまずそれぞれに対して詳細を書いていこうと思います。

結論から先に言う

先ほども述べた、最後まで読まないと何をどうしたいのか分からないという事の何が問題かと言えば、

• 最後まで読む必要がある……言いたい事を理解するのに時間が掛かるし、要点を掴むのにも文章の全てを咀嚼する必要がある
• 読み返す時も、最初に読む時と同程度リソースを要求する

という点です。
なので、まずは言いたい事を先に言ってしまいましょう。
何の為にこの文章は書かれたものなのか？
最終的に何を言いたいのか？
それを最初に提示するだけでも、ぐっと読者のリソースは減ります。
例をざっくり纏めてしまうと、

お勧めユーザー検索に時間が掛かっている問題の解決の為に、検索ロジックそのものを変更したい
“3日以内にログインしている”という条件を”直近にログインをしたユーザーの指定数”に変更したい

という事になるので、まずそれを提示すべきですね。

要点を分かりやすくする

悪い例の文章は、要点が文章の中に紛れ込んでいる為、実際に読んでみないと結論に対して、

• 何の目的でそれをしたいのか？
• それをするメリット、デメリットは何なのか？

と言った事が分かりません。
読者に国語のテストなんてさせるな、って話ですね。
評論文とか書く訳じゃないですし、最初から解答を明示しておけば良いのです。
そういう分かり易さの為には、必ずしも文章の体をしている必要はありません。
必要に応じて箇条書きや強調も使っていきましょう。
それで、要点を纏めてそれを分かりやすくするとなると、フォーマット化してしまうのも良いでしょう。
それだけで誰でも、何も知らなくても、分かりやすいように報告出来るようになるでしょうから。
ただ、フォーマット化に頼り過ぎると報告したい事によってはイマイチ収まりが悪かったりする事もあるので、そこ辺りは柔軟に。
例を要点で分割してみると、

問題:
お勧めユーザー検索で時間が掛かっている

原因:
SV想定より多くのユーザーが遊んでいる
SVの検索処理が最適化されていない
仕様におけるユーザーの参照量が多過ぎる

対応:
ロジックそのものを変更する

対応詳細:
3日以内にログインしているユーザーから対象を抽出する
を、
直近にログインをしたユーザーの指定数
にする。
理由としては以下。
・その仕様が一番冗長且つ時間の掛かる要因
・SVの最適化不足もあるが、DAUの観点からしても参照するユーザー数が多過ぎる
・直近に遊んでいるという条件を崩さない
・上記の変更を行えば、DAUに関わらず参照するユーザー数が一定となりレスポンスがいつでも安定する
また、これに変更するデメリットとして、
プレイ人口が減ると同じユーザーが選出される可能性がある
が、
現状のDAUを考えると殆ど発生しない
と考える為、問題ないと思う。

専門用語は必要に応じて噛み砕く

悪い例において、データベースのインデックスが適切に張られていなかったと説明していますが、
ぶっちゃけプランナーとかになると、エンジニアを経験していたり、DBに対する理解が無かったりしないと、そんな事知らんがなというだけで終わります。
どういう人に読まれるかという事を考えて、専門用語は適切に言い換えたり、抽象化したりしましょう。
この例を書き換えるとすると、
想定以上のユーザー数に対して検索処理に時間が掛かるようになってしまった
データベースの検索の効率化が考慮不足だった
とかで良いかと思います。
他にも、APIだとかDAUだとかリセマラだとか、これらに関しては同じゲームを開発している人達なら基本通じるでしょうが、専門用語には違いないので、ゲーム開発者だったりエンジニア以外に何か説明をする際は、噛み砕いておいたり、注釈を隅に書いておいた方が良いかもしれません。

例を書き換えてみる

フォーマットがあるなら、それに記して出力して終わる……というか、前述の要点を分かりやすくするで書いた形でいいと思うのですが、
先出しとして、チャットツールとかに投げる形を想定して、書き直してみましょうか。

お疲れ様です。
先日より発生している、お勧めユーザー検索で時間が掛かる問題に関して、解決の為に一部仕様変更を願いたいです。
仕様変更したい部分は、検索条件の
3日以内にログインしているユーザーから対象を抽出する
を、
直近にログインをしたユーザーの指定数
への変更です。
詳細を以下に記します。

まず、そもそもの原因に関してですが、
・SV想定より多くのユーザーが遊んでいる
・SVの最適化不足
・ユーザー抽出条件の、3日以内にログインしているユーザーが多過ぎる
が主な問題でした。
また、SVの最適化をしたところで、3日以内にログインしているユーザーが余りにも多い為、それだけでは解決出来ないという結論に至りました。

その対応案として、
3日以内にログインしているユーザー
を
直近にログインをしたユーザーの指定数
に変更したいと考えました。
理由としては、
"お勧めユーザーには、直近に遊んでいるユーザーから抽出したい"という要望を崩さない
ままに、
DAUに関わらず参照するユーザー数が一定となりレスポンスがいつでも安定するようになる
からです。
また、これに変えるデメリットとしては、
プレイ人口が減ると同じユーザーが選出される可能性がある
という事が考えられますが、
現状のDAUを考えると殆ど発生しない
と思います。

ご一考願えればと思います。
よろしくお願いします。

……まだまだ分かり易く出来そうだなー。