会社や研究室でのドキュメント管理について

仕事や研究室などで、でAtlassianのConfluence、GitHub (Enterrise) のWikiやREADME、あるいはPukiWikiなんかを使ってドキュメントを管理しているところは多いと思います。リポジトリのディレクトリ構造の考え方についてGitHubのREADMEに書いたり、ある本番更新の手順書をConfluenceで管理したりしています。僕は、個人的なメモもConfluenceのパーソナルスペースというところで管理したりしています。個人的なメモですが他の人の役に立つこともあるからです。例えば、Memcacheの中身をコンソールから確認する方法など...

とにかく社内ドキュメントに残すことは良いこと

Confluenceなどの社内ドキュメントにこういったことを残すのは非常に良いことです。最近だとPHPのバージョンアップ（PHP5.6からPHP7へ）を行っているサービスもあることでしょう。なるべくユーザー影響が出ないように、慎重にPHP7しようと手順を作成します。この時、過去PHP5.3からPHP5.6にバージョンアップした時のドキュメントが残っていたとすると、、、PHP7へのアップデートの手順も作りやすくなりますよね。

「仕様」をドキュメントに残すことは良いことですし、「手順」をドキュメントに残すことも、後に似たようなことを行う時に参照できるので非常に便利です。

社内のドキュメントは知見の塊。公開できるものは公開したい。

社内ドキュメントは社内の人しかみられません。自分が転職などでその会社を離れても見られなくなってしまいます。

会社というのは、大きくなればなるほど知見の塊です。例えば、chefのリポジトリがGitHub EnterpriseやGitLabにあったとします。社内のサービスの保守をしている場合（新規プロダクトを0から作るという案件でない場合）、chefのリポジトリというものは既に存在していて、せいぜいそこにちょっと何かを付け足す程度の変更しか行いません。その際に、なんの違和感や手間なく、簡単にchefリポジトリへの追加や変更ができるのは、そのリポジトリの保守性が高いからです。すでに美しいディレクトリ構成が出来上がっているのです。

さて、転職したとします。転職先では新規サービスを作ることになりました。chefで構成管理をすることになりました。さて、今までchefにはちょっとしたコードの追加したことしかありません。すでにあるリポジトリに追加することと、新しく1から作成することは全然違います。ここで規模の大きい会社の場合、成功している他のプロジェクトのchefリポジトリを参考にすればいいです。が、スタートアップだったりした場合は参考になる他のリポジトリはないかもしれません。chefのドキュメントは前の会社においてきてしまいました。

こういった場合に、自分がドキュメントをpublicに公開していれば、それを参照できるので便利です。

社内ドキュメントにまとめるのは非常に良いことですが、公開できるのであれば公開されるのに越したことはありません。自分のためにもなりますし他人のためにもなります。ただし、社内の情報は簡単に公開できることではありませんので、公開できることは（汎用的な部分は）公開する、出来ないことは社内のドキュメントにまとめる、という分類が重要になります。なんでも公開、あるいはなんでも社内のConfluenceだと困るということです。