はてなチーフエンジニアの Songmu です。この記事ははてなデベロッパーアドベントカレンダー2015の7日目の記事です。昨日は id:mazco による デザインにおける個性のつけ方 でした。
今日は Mackerel の公開ドキュメントについてのお話です。
Mackerelは以下で公式ドキュメントを英語と日本語で提供しています。
これらは実ははてなブログでホストしています。
翻訳は日本語を先に書いて、それをチームのネイティブ翻訳者が翻訳するフローになっています。
ドキュメントの運営
告知ブログのようなものなら良いのですが、ドキュメントはその性質上定期的なメンテナンスが必要になります。特に以下の様な点がドキュメントを運営する際に難しいところです。
- なんらかの一括修正が必要になった場合に修正点を洗い出して一括で反映する
- 修正差分を翻訳者と連携する
こうなってくると、バージョン管理をしたくなるのが心情でしょう。つまり、はてなブログはドキュメントツールに向いてない、と思ってしまうかも知れません。
はてなブログAtomPub と blogsync
はてなブログはAtomPub APIを提供しており、ブログデータの取得や更新をおこなうことができます。
このAPIをラップして、はてなブログの操作をコマンドラインからおこなえるツールが、
id:motemen 作の blogsync です。
去年の はてなエンジニアアドベントカレンダー でmotemenがblogsyncの紹介をしているので、使い方の大まかな概要はこちらをごらんください。
このblogsyncを使うことで、はてなブログの記事をMarkdownで管理することが可能になります。
blogsyncのアップデート
去年から今年にかけてのblogsyncの大きなアップデートは以下の2点です。
- ヘッダに書くメタ情報の形式をYAML Front-matterに
- --custom-path オプションで、記事の新規作成時にカスタムURLを指定できるように
特に --custom-path オプションが導入されたことにより、ヘルプの執筆が捗るようになりました。たとえば以下のように、新規のMarkdownから独自URLで記事を投稿することができます。
% cat new.md | blogsync post --custom-path=path/new
blogsyncとGitHubを用いたはてなブログでのヘルプ運用
Mackerelチームでは、blogsyncで取得したMarkdownファイルをGitHub Enterprise上のリポジトリ上で管理しており、ドキュメントを修正する際にはpull requestを使うようにしています。
例えば以下は、最近入ったメトリック取得APIのドキュメント修正の様子です。
pull requestにすることで、議論がしやすくなるということはもちろんですが、そのpull requestがマージされた後に、そのpull requestの差分ファイルを翻訳者に連携することで翻訳がスムースになったり、翻訳漏れをなくしたりすることができます。
今後の課題
それなりにはかどっているblogsync運用ですが、まだまだやりたいことはあります。例えば以下の様なことです。
手作業を減らしたい
現状以下の様な作業を手作業で行っているのを自動化したいと思っています。
- masterにマージ後のblogsyncコマンドによる本番反映
- Web上からヘルプを直接編集した場合の変更点のリポジトリ取り込み
公開リポジトリにしたい
公開されているドキュメントをプライベートリポジトリにする理由はあまりないので、可能であれば調整をして公開をしたいと思っています。
まとめ
blogsyncとGitHubを組み合わせたはてなブログでのドキュメント運用について書きました。ブログの運用にも応用できるんじゃないかと思うので興味のある方はぜひご利用下さい。
はてなではMackerelのようなSaaS開発やドキュメントも含めた運用に興味のあるデベロッパーを募集しています。
明日は、 
id:cockscomb が担当します。お楽しみに。
