Markdown と GitHub で社内規程を便利に管理

VP of Technology の星 (@kani_b) です。技術基盤や研究開発領域などを担当しつつ、社内の色々なことを技術の力でいい感じにする仕事をしています。セキュリティや AWS の話が好きです。

さて、みなさんは、ご自身が勤務する会社の就業規則を読んだことはあるでしょうか。 エンジニアに限らず、会社の全スタッフが仕事をする上で関わってくるのが、就業規則や情報セキュリティドキュメントなど、会社のルールや規程を記す文書です。 特にセキュリティやインフラに携わるエンジニアは、その改訂も含め携わったことがある方もいるのではと思います。

よくある文書管理

こうした文書は、以下のように管理されていることが多いようです。

• ベースドキュメントは Word
  • 保存時は PDF で保存
• 版管理は Word の編集履歴 + PDF に保存する際のファイル名
• 編集は担当部門, 担当者のみが行う

かつてのクックパッドでも、上記のように作成された PDF ファイルを Google Drive に保存して従業員向けに公開していました。 この記事を書くにあたり他のいくつかの企業の状況を伺ったところ、細かな差異はあれど同じような運用をされている例がほとんどでした。

つらい点

上記のような管理において、自分がつらいと感じる点がいくつかありました。以下に挙げていきます。

レイアウト難しい問題

複数人で編集することを前提とした文書の体裁を Word や他のワープロソフトで保ち続けるのはなかなか難しいものです。 全員が習熟していれば良いのですが、習熟度に差があると同じレイアウトでさえ記述方法が違っていたりします。 「番号付きリストかと思ったら番号は手動入力されていた」「中央寄せかと思ったら全角スペースの数でレイアウト調整されていた」「改行の数が違うとレイアウトが崩れる」なんてことはよくある話ではないでしょうか。

そもそも、そこまで頑張って整えている体裁は本当に必要…？

版管理難しい問題

ワープロソフト側に版管理の機能が備わっていることも多いのですが、複数人での編集を前提とするとき、全員が意識して同様の管理を行う必要があります。また、担当者の引き継ぎによって文化が失われてしまうような悲しい事態も起こります。 それ以外にも、規程閲覧側に公開されるのは最終成果物である PDF ファイルのみであることが多く、差分を確認するためにはそのバイナリに対応したソフトを利用する必要があります。閲覧側にとっても便利とはいえない状況です。

これら2点が感じていた大きな問題ですが、他にも

• 文書を横断した検索性が悪い
• 複数人でのレビューが難しい

といった問題を感じていました。

社内文書管理に求めていたこと

ここまでに書いた問題を感じつつ、つらい〜と鳴きながら文書編集をしていたのですが、ある日雑談の中でそうした文書管理を担当していた、いわゆるバックオフィスの同僚も同じようなつらさを感じていたことを知りました。 そこで、規程や社内マニュアルなどの文書に求められることを簡単にまとめてみたところ、概ね以下のような条件を満たしていれば良いのでは、という結論に至りました。

• 然るべき責任者の承認のもと編集されていること
• きちんと版管理が行われていること
• 編集すべきときにすばやく編集できること
• 見たいとき、見るべきときにすばやく参照できること
  • 閲覧しやすいフォーマットであることが望ましい

あれ、これって…？

あえてプレーンテキストを使う

というわけで、Word と社内ファイルサーバおよび Google Drive で管理されていた社内文書を、Markdown で書かれたファイルを Git (GitHub) で管理する形に移行しました。

Markdown は、 GitHub 上でリッチな表示を使ったレビューが可能です。また Groupad と呼ばれる社内 Wiki では長年 Markdown 記法が使われていました。このため、Markdown という名前を知らなくても 「Groupad と同じ記法」と説明すれば通じる状況にあり、利用をはじめるにあたりあまり障壁はありませんでした。

Markdown で書かれた就業規則

また、GitHub についても、数年前から全社員に GitHub Enterprise のアカウントが発行されており、人事部門や法務部門も Issue ベースでのやり取りに慣れているといったところから、ある程度スムーズに利用を開始することができました。

GitHub からのファイル編集

Git 移行にあたって最も障壁となりやすいのは、編集作業をどのような環境で行うか、という点だと思います。 素の Git コマンドをターミナルから使ってくれ、ではハードルはどこまでも高くなるだけですので、Git を使ったことがない同僚にはまず GitHub の編集機能を使ってもらうことにしました。 あまり利用されていないようにも思えますが、GitHub そのものにも編集機能が用意されており、ファイル編集や変更の Commit, Branch や Pull Request の作成なども可能になっています。Git の概念をすべて理解してもらうのでなく、使う機能を限定することで、極力移行をスムーズにしました。

改訂フロー

現在の文書改訂フローは以下のようなものです。

• 担当者が改訂案を Markdown で起案し Pull Request を作成
  • 必要に応じて他の担当や上長からのレビューを受ける
• 責任者は確認し、内容に問題がなければ承認とマージを行う*1
  • GitHub の Branch Protection を使い、責任者の Approve がなければマージできないようになっている
  • 会議体の承認が必要な文書は Pull Request のスクリーンショット (記録のため) ごと会議体にまわり承認されたのち、責任者によって Approve される
• マージ後は自動的に公開される

GitHub を使った開発でも行われるようなフローで文書管理を行えるようになっています。

文書の公開

GitHub における Markdown ビューを使っても、文書として読むのに問題ないビューを得ることができます。 ですが、文書の移行をすすめるうち、複数ある社内文書のインデックス作成やカテゴリ分類、少し複雑な計算式表現などが必要になりました。*2

そこで、Markdown が利用可能な静的サイトジェネレータである Jekyll を使い、Markdown で作成した文書から静的ページを生成して社内に公開しています。ドキュメント用の Jekyll テーマである tomjoht/documentation-theme-jekyll を採用しました。 Jekyll は GitHub Pages によって GitHub 側でビルドを行えるので、作成した文書をそのまま提供することもでき便利です。

当初 GitHub Pages による提供を考えていたのですが、例えば入社が内定された (入社前の) 方に公開するなど、アクセス制御の要件が増えてきたため、現在では Jenkins 上で自動ビルドを行って Amazon S3 上でホストしています。

Jekyll でビルドされ公開されている就業規則

クックパッドでの利用状況

現在クックパッドでは、就業規則や賃金規程などほぼすべての社内規程が上記のような形で管理されており、法務部門や人事部門も GitHub を使った文書管理を行っています。 従業員はビルドされた HTML ドキュメントを参照することも可能ですし、元の Markdown を確認することや、Git のコミットログを確認することも可能です。

情報セキュリティのガイドブックといった、改訂しやすい文書は担当者外からの Pull Request も受け付けています。レイアウトの修正のほかに、ルールそのものに対する提案も Pull Request として来るものが生まれており、議論しやすくなったと感じています。

また、文書全体のレイアウトを整えやすくなり、より構造を意識して書くようになったり、従業員からの検索性が上がったり*3といった効果もありました。

あくまで個人的な感想ですが、編集しやすくなったことで、改訂に対する (気持ち的な) 腰の重さも軽くなったように思います。規則やそれを記述する文書は従業員の業務を助けるものであり、会社や世間の状況が変わった際すばやく改訂できる状態を保つことはとても重要と考えています。

まとめ

クックパッドにおける社内規程の文書管理を Markdown および GitHub を使った管理に移行した事例についてご紹介しました。

担当者全員が Git を覚えなければならない世界にするのでなく、GitHub といったある程度親しみやすいインタフェースを間に利用するといったように、担当者や閲覧する従業員にとって良い形を追い求めていくことは非常に重要です。こうした改善は「やりたい人の独り善がりにならないようにすること」がとても大事な、かつ楽しい部分だと感じています。

また、クックパッドでは、今回ご紹介したように技術を活用しながら全社の業務をより良くしたいコーポレートエンジニアや、自らの領域を一緒に改善していける財務・人事といったコーポレート部門スタッフを大募集しております。興味をお持ちいただけましたら、キャリア採用情報 (https://info.cookpad.com/careers/jobs/) から詳細を是非ご確認ください。

*1:軽微な修正のため、担当者の判断でマージできる文書もあります

*2:たとえば、賃金規程において、賃金の計算式を示すのに MathJaxを使っています

*3:現在は GitHub における検索にまかせています