Handbook の書き方
前提
ここで示すものは ToBe であり、これを満たしていないものを Handbook に含めてはいけないという性質のものではありません。 今後修正を加えていくときに少しずつこのガイドラインを満たす形式に収束していければ十分です。 そもそもこのガイドライン自体も Handbook の一部で継続的に更新されるものであるため、 ガイドラインを逸脱するドキュメントの存在を排除するのは現実的に不可能です。 ドキュメントとして存在する Handook は正しい情報が書かれている事が重要であり書き方は二の次で構いません。
推奨項目
ファイル名
各ファイルの名前は Web 版 の URL の一部となります。 統一感のために単語区切りは - で行ってください。
敬体
おそらく多くの人にとって書きやすく読みやすい形式であるため敬体を推奨します。
個人に紐付けない
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 などを書くと良い
もっと知りたい
概要を掴んだ人が更に詳しく知りたいときに見るリンク集
最終更新