Handbook の書き方
ここで示すものは ToBe であり、これを満たしていないものを Handbook に含めてはいけないという性質のものではありません。 今後修正を加えていくときに少しずつこのガイドラインを満たす形式に収束していければ十分です。 そもそもこのガイドライン自体も Handbook の一部で継続的に更新されるものであるため、 ガイドラインを逸脱するドキュメントの存在を排除するのは現実的に不可能です。 ドキュメントとして存在する Handook は正しい情報が書かれている事が重要であり書き方は二の次で構いません。
おそらく多くの人にとって書きやすく読みやすい形式であるため敬体を推奨します。
Handbook はエンジニア組織として継続的に更新していく必要があるものです。 実際にはある個人がほぼ全てを執筆した章もありますが、 より積極的な更新提案を社内から受け付けるために Handbook のすべてのテキストは個人に紐付くものではないことを共通認識として持ちます。 したがって下のような表現を避けましょう
- フロントエンドエンジニアの xx です。
- 同じチームの yy さんが作っています。
- 私の考えでは
- 個人的な意見としては
- と思います/考えます
リンクを追加する場合は物理本で読む人がいることを意識しましょう。 物理版ではリンクは脚注で記載されますが、実際にそのURLを自分でタイプすることは稀であると考えられるので、 前後の文脈でどんな場所に書いてあるのかが想像できるようにするのが望ましいです。
この Handbook は社外にも公開されていますが、社内の人しか閲覧権限がないページへのリンクを記載することは基本的に問題ありません。 特に GitHub の repository, commit, issue, PR へのリンクを張ることは問題ありません。 ただし読者の混乱を避けるため、
とある社内ドキュメント (internal) のように (internal) という文字列をつけることを推奨します。この Handbook はブログや研修の内容を転用した章を含んでいます。 そういった章ではコンテキストを示す「Wantedly では」のような表現がありますが、 Handbook ではこれは前提となる情報であるため特に明示したい場合を除き削減していくことを推奨します。
下の2つの目的のためあえて読み物としての読みやすさではなく局所的な読み書きのしやすさを優先します。
- 読み手が高速にエッセンスを把握できるようにする
- 書き手が修正を行うときの影響範囲を狭くする
このため情報の羅列になることを許容し、読み物としてのわかりやすさを求めません。
Handbook では new joiner が高速に知るべき情報を知れることが重要です。 多くの場合は「何を知るべきなのかそもそもわからない」ことが問題になるので Handbook の章を書くにあたってなにを書いてよいかわからなくなる場合は、「何を知るべきか」を書くだけでも構いません。 誰に聞けばよいか、どこを見ればよいかがわかることが最低条件です。 具体的に簡単に概要を説明した上で細かい説明は他のドキュメントに譲って問題ありません。
新たなドキュメントの書くときは下のフォーマットを参考にしてみてください。
- 想定読者
- 例1: フロントエンドエンジニア
- 例2: インフラチームにタスクをお願いする人
- 例3: モバイルアプリが関わるプロダクトを開発する人
- 歴史 (optional)
- これまでの技術選定の変遷などを記載すると new joiner がコンテキストをつかみやすい
- 話を聞きに行きたい
- 誰に聞くとより詳細なことがわかるかを書く
- Slack の channel、GitHub の team などを書くと良い
- もっと知りたい
- 概要を掴んだ人が更に詳しく知りたいときに見るリンク集
最終更新 1yr ago