READMEとWikiをハックする
開発規模が大きくなるに連れてREADMEとWikiの重要度が増す
個人や単一のプロジェクトのみの頃はいいのですが、会社の規模に合わせて 人が増え、ドキュメントが増え、プロジェクトが増えます。 弊社ではgithubを使ってソースの管理をしています。
そうなってくると同じ言葉でもプロジェクトごとに違う意味合いをもったり、 営業や運用サイドの人がissueを立てる機会も増えるものです。 そんな時、ふとコミュニケーションコストが結構あるなと思いました。
wikiに書いてあるもののプレフィックスの付け方で情報にたどり着けなくて質問したり、 サービスの流れやバッチの詳細がわからずに要件を詰め直すミーティングをしたり。 ここはREADMEとwkikiを整備してどのプロジェクトでも これはREADME見れば書いてある、これはwikiのこういうプレフィックスの場所に格納されてるとわかるようにすればいい！と思い立つわけです。
README
READMEにはプロジェクト概要とスタック、スタート方法を担わせます。 とりあえずREADMEみときゃフレームワークやら言語のバージョンがみらるようにするのが狙いです。
最低限の情報を簡潔にまとめ、できるだけ日本語の平易な文章にします。 これは運用サイドの人でも読めるようにしておくためです。 彼らは英語のドキュメントは読んでくれません。ググレカスは通じません。
そこにわかりやすいものを載せるこれだけの労力でコミュニケーションコストの 圧搾ができるなら手間をかけましょう。
Wiki
ここではエンジニアのための詳細な情報やテストの手順、デプロイなど サービス運営に置いての情報を一気通貫で置いておきます。 肝心なのは命名です。 これはwikiでも一緒。リーダブルなプレフィックスをつけましょう。(統一してください) ここでもルールは簡単にしておきたくて、 基本ルールは - 情報のまとまりはコンパクトに - 意味を揃えた言葉の使い方をする くらいでしょう。
それぞれを統一フォーマットを下敷きにする
ここでいちばん重要なのは言葉の意味の統一すべき部分の切り出し。 プログラムを書く上での単語レベルまで揃える必要はないですが、 説明の時の文章には使い方を統一した単語選びが重要です。
時に運用がみるページには最大限のおもてなしの心でwikiを書きましょう。。。
まとめ
README編
- 書き方のフォーマットを作り運用
- 丁寧に作りすぎないことがポイント
- READMEの内容に変更があったことをログとして残したい(PR出せばいいのだろうけど面倒)
ここでの重要ポイントは統一フォーマットを下敷きにしてREADMEのプロジェクトごとの違いをなくすこと。 wikihへの誘導などがあると新しく人員が増えた時に質問コストが下がるので便利。
wiki編
- 同じく基本フォーマットを作る
- 項目の情報は最小単位の情報で！
- プレフィックスの付け方一つで格段に運用コストが下がるのでめんどくさがらないこと
READMEの足りない部分やプロジェクト独自の動きや操作等をまとめる。 一つの項目での情報を欲張らないようにしてコンパクトに！
所感
プレフィックスの付け方一つでここまで運用や新規ジョイン時にかかるコストが下がるとは思わなかった。 運用サイドの人が見る場合には非エンジニア向けの項目も追加しておくと やりとりが格段によくなり、情報の属人化を緩やかに緩和できると思った。 コミュニケーションコストの増加を招く原因は情報の場所の乱雑さ、そして統一されない言葉の意味にある。 言葉の意味の統制をするのは現実できでないならwikiやREADMEはせめて統一された意味を持つものと個別に意味を持つものを明確に書き分けて行きたいと思う。 ここまで時間のレバレッジと質問コストが下がるならば一つ真剣に取り組む価値があると思う。 ぜひ皆さんもREADMEとwikiを整備してHappyな開発ライフを！
