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