チームで情報をスタックするためのwikiの運用で気をつけていること

僕のいるチームではConfluenceを使っているが、一般的なwikiのようなものであれば適用できる話だと思う。
ちなみにこれは個人的に気をつけていることであって、他のメンバーに強制してるとかはない。
twitterとかblogのようなフローの情報ではなく、スタックするタイプの情報管理は、下記のようなことを意識してないと結構すぐに破綻する気がしてる。

階層を深くしすぎない

wikiはサイト全体をツリー構造に構築するものだが、だいたい3~4階層までにしときたい。
深すぎると辿っていくような遷移をする時に面倒だから。
wiki全体の階層構造としては、大体下記くらいの深さ&粒度が良い気がしてる。

-- Installation
   |-- moduleA
   |-- moduleB
   |-- :
   `-- :
-- FYI
   |-- rails tips
   |-- git tips
   |-- LGTM images
   |-- :
   `-- :
-- Dev&Ops
   |-- CI
   |-- source code management policy
   |-- trouble shoot
   |-- :
   `-- :
-- Minutes
   |-- daily scrum
   |   |-- 2014-01
   |   |-- 2014-02
   |   |-- 2014-03
   |   |-- :
   |   `-- :
   |-- :
   `-- :

ページを細かく分けて増やし過ぎない

何か書こうと思った時には、新しいページを作りたくなるんだが、ページが分かれすぎてると見る人が大変になる。
なるべく同じページ内で章を分けたりして、ページが乱立するのを避ける。
開発関連のドキュメントの場合は、一つのページが縦に長くなっていても、そんなに気にならないと個人的には感じている。

別のページをincludeはなるべくしない

なんか、includeしてるorginのページを編集するのがすごく面倒だから、includeはなるべく使わないようにしている。
たいていはリンク貼っておくだけで全然問題ない。

検索可能にする

当たり前だけど、文字なら文字として書く。
confluenceには”この階層以下を検索”とかって機能があって、結構それ使って検索することがある。
画像貼っただけのページとかだと、キーワード検索で引っかからなくてつらかったりする。

英語と日本語の両方で書く

チームには日本人もいるし外国人もいるので、下記のように英語と日本語に両方で書いてる。

We use rspec version3.(私たちはrspec3を使います。)
Should keep code coverage 100%.(テストのコードカバレッジは100%を保ちましょう。)

メンテする

これが一番難しくて今でも困ってるんだが、ドキュメントは時間が経つと腐っていくので、適宜内容は更新していかないといけない。
APIドキュメントとかならコードから機械的に生成するとかもやったりしているが、
機械的に生成出来ない類のドキュメントもあるし、これはもう定期的にチェックしていくしかないかなーという気がしてる。
賞味期限を設けて、それを超えるとアラートするとかすると辛くなりそうだしなぁ。

まとめ

いろいろ書いたけど結局のところ、メンバーが見やすく探しやすく書きやすい状態を保っときたいという話でした。