GitHub Pagesを活用した、社内ハンドブックの取り組み
情報共有やナレッジマネジメントの重要性はすでに認識されており、SaaSを活用しながら力を入れている企業は増えています。一方で最適解はなく、常に課題を認識しながら運用している企業も多いのではないでしょうか。
ROUTE06では全社でGitHubを活用しており、GitLab Handbookを参考に、全社に関係する情報をハンドブックとしてGitHub Pagesで社内に公開しています。
本記事では、どのように運用しているのかを紹介させていただきますので、事例の一つとして、参考になれば幸いです。
GitHub (GitHub Pages) を選んだ背景
全社ワークスペースをGitHubにしたことで、日常的にGitHubを活用するようになりました。タスク管理や目標管理はGitHub IssuesとProjects、議事録や日報はGitHub Discussions、簡易的な承認はPull requestsで行うなど、広く利用されています。
GitHubの利用が浸透したことで、全社に影響する取り組みをGitHub上で実現することができる環境になりました。
このような背景を生かして、GitHub Pagesを活用した、社内向けハンドブックの運用を2022年12月より開始しました。
利用している技術
利用している技術は次のとおりです。
GitHub (Enterprise)
大きな負担なく運用できるよう、シンプルな構成となっています。
GitHubはEnterpriseプランを契約することで、Private Pagesの作成が可能になり、そのリポジトリを見られる人だけがそこから生成されるPagesのサイトを見られるという設定を行うことができます。
この機能を活用し、DocusaurusをStatic Site Generatorとして使用することで、社内メンバーのみがアクセス可能なハンドブック環境を実現しています。
Docusaurusを選んだ理由
ハンドブックの環境を構築するにあたり、以下のような点を意識して選定しました。
全社で日常的に参照され、変更するべき点については気軽に提案、直接コントリビュートができること
関連情報が集約され、存在するドキュメントが更新され続けること
検索可能であること
自分たちで運用する場合は、維持が比較的容易であること
もし合わない場合には乗り換えが可能なように、ドキュメントが持ち出し可能であること
社内利用であり制約が少ないため、楽しんで改善ができること
有料SaaSの利用なども同時に検討していましたが、検討時期にちょうどDocusaurus 2.0がリリースされたばかりで注目度も更新頻度も高く、Docusaurusが利用している技術は社内のメンバーとも相性が良さそうであり、上にあげた項目も満たせそうなことから、採用を決めました。
更新しやすくするための工夫
Docusaurusでは、情報をMarkdownファイルによって管理しています。
情報の追加や更新を行う際には、GitHubのリポジトリにアクセスしてファイルを追加・編集、Pull requestを作成し、CODEOWNERのレビューを経てマージするという流れになります。
Pull requestの作成は、ファイルの追加・削除の操作やCommitの操作なども学ぶ必要があり、最初は少しハードルがありましたが、今では広く日常的に行われるようになりました。
しかしながら、運用上の課題として、以下のような点がありました。
本番環境へ反映された場合にどのように表示されるのかを確認するためには、ローカル環境で実行する必要がある
MDXの仕様上、Markdownファイルにimgタグを記述する際は末尾にスラッシュをつけないとシンタックスエラーになったり、Markdown記法が人によってばらつきが生まれたりなどの課題がある
プレビュー環境の用意
表示確認のハードルを下げるため、Pull requestが作成されたら、GitHub Actionsを用いてプレビュー環境を用意するようにしました。
GitHub Pagesで運用しているため、プレビュー環境用のリポジトリを別で用意、Pull requestが作成されたらそちらにデプロイし、変更があったページのプレビューURLがPull requestにコメントされます。
確認のハードルが大きく下がり、Pull requestのレビューもスムーズになりました。
各種lintツールの導入
imgタグのシンタックスエラー解消のほか、Markdown記法に沿っていない記述を指摘したり軽微なものは自動的に修正するため、eslintやmarkdownlintを導入しています。これらはGitHub Actionsで実行され、Reviewdogを使用しPull Requestにコメントとして追加しています。
レビューコストが下がっただけでなく、執筆者のMarkdown記法のスキルアップにもつながっています。
利用状況と今後の課題
2022年12月より運用を開始、2023年7月時点では、300件強のMarkdownファイルが共有されています。関連情報の分散を防ぐため、現在は1つのファイルに関連情報やTipsなども含めて情報を追記する方針としています。
毎日のようにPull requestが作成されて更新が行われており、社内のメンバーがコントリビュートしていることからも、上にあげた要件は現時点では概ね満たせていると感じており、このまま引き続き改善していけたらと考えています。
また、新たな工夫として、ROUTE06では現在数多くのリポジトリが存在しますが、その中でも特に主要なリポジトリについて、README.mdを自動的にハンドブックへと同期し、ハンドブック上からREADME.mdを確認できる環境を構築中です。これにより、主要なリポジトリについてはREADME.mdを更新することで情報の見通しが良くなり、リポジトリのREADME.mdが正しく活用されるようになることを期待しています。
追加や編集が日常的に行われて、さまざまなドキュメントが自然と追加される状態になった反動として、全体の情報量が増えてきました。今後は、構造的に捉えやすいよう情報の分類を工夫し、配置場所をわかりやすくすることで、組織の拡大や取り組み内容の複雑化にも対応した形で情報が流通するようにしていきたいと考えています。
引き続きハンドブックの改善を進めるとともに、働きやすい環境を実現するために他にもさまざまな取り組みを予定しています。また実装できたら、ご紹介できればと思います。
｜関連記事｜