WebエンジニアのLoL日記

LoLをプレイしたりLJLの試合を見たりするのが好きなエンジニア。LoLのイベントやパッチノートなど気になった点を記事にしたり、LJLについの記事をかいたりしています。某社でWeb系のエンジニアとして働いているので、技術系の記事もたまに書きます。コンタクトを取りたい場合はtwitterまで。

【雑談】github.ioとmarkdownでいい感じに知見を管理・共有したい

これは技術的な記事というよりも、最近思っていることを書いただけの記事です。

最近、GitHubMarkdownで知見をいい感じに管理・共有したいと思っています。

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

仕事や研究室などで、で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だと困るということです。

では技術をどうやって公開していくのか

では、公開していくことを決めた時に、どうやって公開していくか、を考えることになります。

今は主にブログで情報を公開している

僕は、今はブログで情報を公開していくようにしています。超個人的に学んだことはもちろん、会社で何かをして学んだことのうち、公開して良さそうなものについては積極的にブログに書いていっています。

しかしブログにはいくつかの欠点があります。

  • 古い記事は流れてしまう
  • 長い記事は読みづらい

ブログは「タイムライン」なので、記事の「管理」という側面から見ると向いていません。Confluenceみたいに、記事をツリー構造で管理したいのです。

そこで GitHub IO を使いたい

そこで GitHub IO を使って管理したいのです。問題はコンフルみたいにツリーで管理したい点ですね...

例えば過去にこういうページを作ったことがありますが。

トップページ - @yoshiki_utakata

このツリーは自分で書いているだけなんですよね。mdからhtmlへの変換はgithubにpushされたら自動で行ってくれるようになっているのですが、あとはページのツリーをなんか簡単にいい感じに表示してくれる方法が知りたいと思っている今日このごろでした。

このてブログは簡単に公開できるので、しばらくはブログをつかっていくかもしれません。