無印吉澤

Site Reliability Engineering（SRE）、ソフトウェア開発、クラウドコンピューティングなどについて、吉澤が調べたり試したことを書いていくブログです。

社内Wikiに情報を書くときに守ってほしい、たったひとつのルール

Wiki
f:id:muziyoshiz:20160425013924j:plain

このページについて

これは、社内 Wiki に情報を書くときに、私が個人的に守っていて、チームメンバにもできるだけ守ってほしいルールの紹介記事です。このルールを実際に運用するためのコツについても、基本ルールの派生という形で紹介します。

想定する環境

この記事は、社内に Wiki があって、フォーマットが決まったドキュメント（仕様書や手順書など）とは別に、各人がメモを自由に書いて共有できるような環境を想定しています。

Wiki の種類は問いません。PukiWiki、MediaWiki、Confluence、Esa、Redmine などのプロジェクト管理ツール付属の Wiki などなど……何でもいいです。Word 文書などにも適用できなくはないですが、文書を気軽に分けるのが難しい場面には、あまり向かないかと思います。

ルール：「このページについて」という欄をページの先頭に用意し、そのページの概要を1〜2文で書く

守ってほしいルールはこれだけです。単純ですが強力で、きちんと守ろうとすると意外と面倒なルールでもあります。

例えば、何かのインストール作業をメモしておきたい場合、「このページについて」欄には以下のような文章を書きます。

## このページについて

これは、システムAの開発環境を構築するために、Windows 7 にソフトウェアBをインストールした際のメモです。

## 手順

（これ以降に、実際に実行した手順のメモ）

または、何か新機能の実装をしたくて、事前に設計を検討した場合は、こんな感じで書きます。

## このページについて

これは、機能Cの設計についてチーム内で議論するために、個人的に作成した設計案です。設計の事前知識として、既存のソースコードを調査した結果も含めています。

## 設計案

（これ以降に設計案とソースコードの解説）

Wikipedia の記事は、よく「〜とは、…である。」という一文から始まりますが、それをイメージしてもらえると分かりやすいかもしれません。

同じような内容がページの先頭に書いてあれば、この欄の名前は「このページについて」にしなくても、「概要」でも "About this page" でもなんでも良いです。

このルールの目的

このルールを徹底する目的は、そのページを開いた人に 「このページに、自分がいま知りたい情報が書かれているか？」を瞬時に判断する ための情報を与えることです。

社内 Wiki を実際に使っている人なら、このページにはこんなことが書いてあるだろうなーと思って読み始めたら、実際は全然違うことが書かれていた、という経験が何度もあると思います。例えば、こんな感じです。

  • インストール手順書かと思って読んでいたら、インストール時に試したことを適当な順序で書いてあるだけのメモだった。書いてある手順を上から順に実行したところ、途中で失敗してしまった。で、メモにも「このコマンドは失敗した」とか書いてある。
  • ある機能の設計に関するメモかと思ったら、単なる設計案の一つだった。最終的に実装されたソースコードの設計とは全く一致していなかった。

誤解を避けるために強調しておくと、私は、中途半端なメモを Wiki に書かないで欲しい、とか、そういう中途半端なメモは消して欲しい、とか言いたいわけではありません。

ただ、そのページがどういう状態なのかが明示されていないと、

あるページAを、ここには正確な情報が書いてある、と思って読み始める
↓
期待を裏切られる
↓
別のページBを、ここには正確な情報が書いてある、と思って読み始める
↓
期待を裏切られる
↓
この Wiki に書いてある情報はどれも信用できない！ となって Wiki を読まなくなる

という悪循環を起こしかねません。そうなると他の人がいくら Wiki に有効な情報を書いていっても、その情報は読まれない、というもったいないことになってしまいます。

ページの先頭にただのメモだと明示してあれば、読み手が 「他に有力な情報源が見当たらないので、これを頑張って読み解こう」 と判断することも十分ありえますし、結果として必要な情報が書いてなくても、期待を大きく裏切ることにはなりません。Wiki 全体でそういう状態を保ち、モラルハザードを防ぐ……というのがこのルールの目的です。

以下は、このルールを実際に運用するために守ったほうがよい、このルールの派生系です。

派生(1)：ページを更新し終わったタイミングで「このページについて」の内容を見直す

ページの内容を色々書いているうちに、最初に書こうと思っていた内容とはズレていってしまう、ということはよくあると思います。理想的には、内容がズレた時点で直したほうがよいのですが、少なくともページを更新し終わったタイミングでは必ず直すようにしましょう。

例えば、設計案を色々書いていたつもりが、最終的な設計についてもそのページに書いてしまい、他のページにはそこまで詳しい情報がまだ書かれてない、という状態になったとします。

もちろん最終的な設計のページをきちんと用意したほうが良いですが、「このページについて」欄を以下のように直すだけでも、後から読む人にとっては役立ちます。

## このページについて

これは、機能Cの設計についてチーム内で議論するために、個人的に作成した設計案です。最終的に採用したのは案3で、このページに書いてある案3の詳細は、最終的な設計と同じです。

派生(2)：「このページについて」から外れる内容が増えてきたら、別のページに分ける

書いているうちに「このページについて」には書いてない内容が増えてきた、あるいは内容に合わせて「このページについて」を直したら1〜2行では収まらなくなった、という場合にはページを分けましょう。

例えば、あるシステムAの開発環境構築手順書を作っているうちに、内容が膨らんできて、「このページについて」欄が、

## このページについて

これは、システムAの開発環境を構築するための手順書です。このシステムのサブシステムB、C、Dの知識がないと、この手順は意味不明に見えるかもしれません。そのため、このシステムのサブシステムB、C、Dの関係についても、構築手順書の途中で説明します。

のようになったら、恐らくそのサブシステムB、C、Dの解説は別のページに分けたほうがいいでしょう。そして、以下のようにリンクを書くだけにするのが無難です。

## このページについて

これは、システムAの開発環境を構築するための手順書です。これらの手順が何をしているか理解するためには、このシステムAの構成に関する知識が必要です。システムAのサブシステムについての知識がない場合は、必ず先に [サブシステムの解説](http://wiki.example.com/subsystem) を読んでください。

そうしないと、読み手が、1個の長いページのなかで、自分の知りたい情報を探しまわる羽目になってしまいます。

別のページに分けたら読まれないかも？と思うかもしれませんが、そういう人は、同じページ内に書いてあってもどうせ読みません。それなら、読む気のある人向けに、少しでもわかりやすくしたほうが良いです。

派生(3)：他の人が書いた「このページについて」も直していい

他の人が書いたページでも、「このページについて」に書かれた内容と、本文が違っていたら、積極的に直しましょう。また、そもそも「このページについて」欄が無かったら追加しましょう。

基本ルールに書いた通り、目的は Wiki 全体の利用価値向上、モラルハザード防止です。そのためには、内容は直さずに、「このページについて」欄を直すだけでも十分意味があります。

例えば、あるページを読んで、その内容が間違っていた場合、私だったらこういう文章をページの冒頭に書いて、内容は修正も削除もせずに残しておきます。

## このページについて

私（吉澤）が 2016-04-25 に調べた範囲では、このページに書かれた設計は、現在の実装と違っているようです。そのため、設計情報としては参考にしないことを推奨します。

ただ、当時の設計思想など、何かの参考になる可能性を否定しきれないため、削除せずに残しておきます。

派生(4)：本文は頑張らない

Wiki に書かれた情報の品質は高ければ高いほど良いですが、敷居が上がって、Wiki に書くのが一人か二人だけ、になってしまうのも困ります。そのため、「このページについて」欄以外のルールはあまり多くしないほうが良いでしょう。

また、一般的な話として、「他人のために細かく書いてあげている」というつもりで書いていると、読んでもらえなかったときの心理的ダメージが大きいです。そのため、手間のかかる本文の品質は、自分が後で読んで困らない程度にしておくことをお勧めします。

まとめ

今回は、普段はあまり書かないタイプの、仕事のノウハウについての記事でした。

私は自他共に認めるメモ魔で、やたらあちこちにメモを書き散らしています。そうやって書き溜めているメモがたまに同僚から「役立った」と言ってもらえることもあるのですが、それと同時に「自分はそこまでできないし、やらない」という反応をされることが多かったりします。

書く分量が少なくても、少しの工夫で、後から読んで役立つような文章を書くことはできるはずなんだけどなあ……と思い、自分なりに本質的と考える部分をまとめてみました。Wiki も普及してだいぶ経つので、今更感のある話題ではありますが、他の人のノウハウも色々伺ってみたいところです。