リモート開発を助ける「思いやりのある文章」の書き方

新しいプロジェクトに参加してローカル環境を作り始めると、何かとエラーに遭遇します。 また、設計や実装について開発者に相談したり、コードレビューを依頼することもありますね。

開発者が近くにいれば、（それなりに、程よいタイミングを見計らって）話しかけて、エラーの原因を調べてもらったり、設計方法をホワイトボードにスケッチしながら相談できますが、リモート開発ではそうはいきません。

リモート開発で成果を上げるためには、このブログのように何の装飾もインタラクティブ性もない文章で、自分の状況や相談したい事柄を正確に伝える必要があります。

とはいえ私は昔、「文章がわかりにくい」と毎日、毎日上司にフィードバックをもらうくらいには文章を書くのが下手くそでした。今もわかりやすい文章が書けている自信はありません。

それでも、これまでに何度か、議論が好転したり、プロジェクトが前に進むきっかけとなる文章を書けたことがあり、このような文章を高い頻度で書きたいと、共通する法則のようなものがないか探しました。それが「読む人への思いやり」でした。

しかしながら、「思いやり」はすごく曖昧で人によって解釈が異なる（それが良さでもある）言葉で、もう少し説明が必要だと思うのでこの記事を書きました。

リモート開発で重要視されることが多いテキストコミュニケーションに苦手意識を持っていたり、課題を感じている人に、何かしらのきっかけを与えられることを願っています。

心がけ

まず、結城浩さんの『文章を書く心がけ』を紹介します。後ほど、文章を書く時の工夫や小技を紹介していくのですが、それらは『文章を書く心がけ』に書かれていることを達成するための手段です。

紹介した工夫や小技が開発の進め方やチームの状況によって使えないこともあると思いますが、『文章を書く心がけ』は普遍的な内容で、いつでもどこでも大切にしておきたい心がけです。

www.hyuki.com

ここで話されていることを強引に一言でまとめさせてもらうと「文章を書くときは読者のことを考えよう」ということだと思っています。当たり前に感じますが、文章を書き始めると途端に難しくなる「読者のことを考える」ということについて、具体的な振る舞いや行動のヒントが紹介されています。

本当に大切なことが書いてあるので、ここから先を読む前に一度、上から下にスクロールするだけでもいいので、見てみてください。

OSSのテンプレートから学ぶ、エラーの報告方法

よく使われているOSS(Open Source Software)には、世界中の利用者からエラー報告が寄せられています。文化や習慣の違う人たちが報告するので、何も決めてないと、エラーメッセージだけ書かれたエラーが報告され、調査や修正に時間がかかります。

そこでOSSによっては、エラー報告のテンプレートを用意し、これに沿っていない場合は無視するようなルールを運用しています。このテンプレートには、距離も時間も離れた開発者同士が効率的に問題を解決するための工夫が蓄積されていると思っており、よくあるものをまとめました。

OSSのエラー報告テンプレートによく含まれている項目

エラー報告のテンプレートには以下の5つの項目が含まれていることが多いです。

項目	内容
環境情報	OSSのバージョンや、OSSを使っているOSの種類やブラウザのバージョンなど
再現手順	エラーが発生するまでの操作手順
期待する挙動	上記の手順の結果、期待していた結果
実際の挙動	上記の手順の結果、実際に起きた結果 例) エラーが出た、意図しない表示になった
再現できる環境	ここまで書いた事象が再現できる環境へのリンク よくあるのは、再現用にレポジトリを作ったり、StackBlitz*1やReplit*2のようなブラウザでコードを実行できるサービスで再現できる状態を作ったりします

エラーが発生した時に、都度issueを作って相談するかどうかはチームの方針によると思いますが、issueでなくてもこの項目を意識して文章を作るとわかりやすくなることが多いです。

私がエラー報告で使っている定型文

私の所属しているチームでは、まずはSlackでエラーを報告し、対応方法を相談することが多いです。その時に書いている文章を読み返してみると上記のissueと同じような内容が含まれていることが多かったです。

{期待していたこと}{起きたこと}
{再現手順}
{環境情報}

具体的には、こんな感じの文章です。

GraphQL Codegenを使って、Fragmentからモックを生成しようと思ったのですが、エラーになりました。
`st/codegen-error`ブランチで、以下のコマンドを実行すると再現します。
pnpm codegen

知識ある開発者が最小の手数で再現できるように自分が時間を使う

OSSのIssueのテンプレートと、私のSlackの定型文に共通しているのは「知識ある開発者の手元に自分と同じ環境を、できる限り開発者の時間を使わずに再現すること」だと思います。

既存のコードを1文字修正したり、1行足すだけで解決するエラーに私は数多く出会ってきました。ただ、その1文字や1行にたどり着くまでには幅広い知識や経験が必要なことも多かったです。

そんな時、OSSのメンテナンスをしている人や、チームにいる知識のある人の力を借りることで問題を素早く解決できます。ただ、そういう人は人気者なので忙しいです。エラーの内容や再現方法がわかりづらいと見てもらうことは難しいでしょう。

そこで、1秒でも短く、一手でも少なくエラーを再現できるようにエラーを報告する側が時間を使うべきだと私は思います。仮に自分が15分かけて再現手順を用意した結果、知識ある人が3分で修正できたなら、それはものすごく価値ある時間の使い方でしょう。

私も最初のうちは、ちょっと面倒だなと思うこともありましたが、今は、誰かの力を借りる上での最低限の思いやりだと思っています。

本当に小さい小技3選

ここからは、私が行なっている細かい工夫を3つ紹介します。チームの方針や状況に応じては使えないこともあると思いますが、参考になれば幸いです。

許可を求めるのではなく、お願いする

相談する時の小技です。

例えば、ミーティングを設定する前に「新機能の仕様について相談してもいいですか？」と許可を求めるのではなくて、先にミーティングを設定して「16時から新機能の仕様の相談をするミーティングを入れたのでお願いします」というようにお願いをすると、コミュニケーションの回数を一回減らせます。

これは、時間を効率的に使うための工夫です。リモート開発ということは、相手がすぐに返事ができる状態ではないことが多いです。返事を待っている間に16時になってしまうかもしれません。

であれば、先に予定を入れておき、必要な資料を準備することで、待つ時間をなくせます。最終的に都合がつかずにミーティングがキャンセルになっても、作った資料を共有して非同期に検討が進められることも意外とあります。

この方法はチームのスケジュール管理の方針やツール、相手との関係性にもよるのでいつでも使えるものではないのですが、おすすめです。

これを応用すると、仕様の相談をするときに、「A案・B案どっちがいいですかね？」ではなくて、「A案・B案あるんですが、こういう理由でA案で進めさせてください」とお願いできます。相手は「A案でOKです」か「A案だとこういう時どうなりますか？」や「それはダメなんです」とすぐに議論が始められます。

（本当に）声に出して読む

書いた文章を送信する前に、本当に声に出して読みます。目で追いながら黙読するのではなくて、口を動かして声を出します。誰かに話すように読みます。すると、不自然な表現や、意味が分かりにくい表現、冗長な表現が見つかります。主語、述語の関係がわかりにくかったり、「てにをは」*3が読みづらい並びになっていたりします。

読んで自然になるまで繰り返すと、最初に比べてある程度わかりやすくなっていると思います。

百聞は一見に如かず

リモート開発で使われている多くのツールでは、画像や動画を文章に添付することができるので、これらの使い方を紹介します。

ウェブアプリケーションやスマートフォンアプリなど画面を操作するプロダクトの場合は、特定の画面の特定のボタンを押したときのエラー報告や仕様の相談をすることが多いです。そんな時は、対象画面のスクリーンショットを添付しておくと、報告や相談の対象が一目でわかるのでおすすめです。

そして、スクリーンショットは、矢印や図形、テキストでデコりましょう。画像だけ見た人が前後のテキストを読まずともなんとなく状況がわかるとベストだと思っています。

スクリーンショットのみ	スクリーンショット+デコ

この画像は、FigmaのVariables機能*4について質問する状況を思い浮かべて作りました。

また、報告や相談の対象が、複数の操作や複数の画面になる場合は、動画を添付することも有効です。例えば、

1. ログイン画面でパスワード再設定リンクを押す
2. ブラウザバックする
3. ログイン画面が表示される
4. ログインしようとすると必ずログインに失敗する

というようなエラーに遭遇したときは、その様子とデベロッパーツールに表示されているログを動画にすると状況がわかりやすいです。

こういったことを素早く、何回もやるには、OSに搭載されているキャプチャツールでは物足りないことが多く、私は色々なツールを使っています。詳しくは別の記事で紹介しようと思いますが、簡単に紹介しておきます。

名前	金額	紹介
Arc	無料	Chromiumベースのブラウザーアプリケーションです。高機能の画像キャプチャが内蔵されています。上記のfigmaのキャプチャに矢印やテキストを書き込んでいるのはこれです。
Cleanshot	$29(買い切り)	Arcはブラウザの中しかキャプチャできないので、より自由度が高く、高機能なキャプチャが必要であればおすすめのアプリケーションです。
Kap	無料	画面収録した内容を数クリックでgifとして出力できます。出力サイズやコマ数も設定できるのでファイルサイズの調整もしやすいです。

arc.net cleanshot.com getkap.co

おまけ: 文章の書き方は意外と見られている

昔、ゲーム開発者の方から聞いた話を紹介します。ゲーム開発にはテスターという開発中のゲームをプレイして、おかしなところを報告する仕事があります。

その開発者の方はそれなりに大きなゲームを開発されていてたくさんのテスターと仕事をしてこられたのですが、テスターからの報告文章を見ると、「この人の報告はいいな」と思うことがあったそうです。

テスターはアルバイトとして雇用することが多かったようなのですが、良い報告文章を書くテスターは社員にならないかと相談することもあったそうです。

今回紹介した工夫や小技で評価される保証はないし、評価されるためにやるものでもないのですが、思いやりを持って文章を書き、仕事をしていきたいですね。

*1:https://stackblitz.com/

*2:https://replit.com/

*3:「てにをは」とは、「は」「を」「が」「も」「に」など、語句と他の語句との関係を示したり、文章に一定の意味を加えたりする言葉のことを指します。 「てにをは」の使い方を誤ると、文章のつじつまが合わなくなったり、ニュアンスが全く違う文章になってしますので要注意です。/ 今さら聞けない！「てにをは」って何だろう？ | 自費出版の幻冬舎ルネッサンス https://www.gentosha-book.com/method/trivia/whats-tenioha/

*4:変数を使用して、さまざまなブランドテーマやデバイスフォーマットなど、適応可能なデザインを作成できるようになりました。また、変数はトークンとしてエクスポートできます。|#Config2023 発表その2：バリアブル/https://twitter.com/FigmaJapan/status/1671611701073186816