Zenn
🗺️

cybozu developer network のアーキテクチャ 2023 年度版

2023/12/04に公開
Amplify
Hugo
tech

はじめに

こんにちは。
サイボウズ製品の開発者向けドキュメントサイト「cybozu developer network」の運営をしている、テクニカルライター兼エンジニアの @_chick_p です。
チームの採用面接のときに、cybozu developer network のアーキテクチャについて質問されることがあるので、アーキテクチャと技術スタックをまとめてみました。

このページの内容は 2023 年 12 月時点の情報で、今後変更になる可能性があります。

Docs as Code

サイトアーキテクチャを説明する前に、ドキュメント管理に置いて重要な考え方である「Docs as Code」を紹介します。

Docs as Code [1] とは、「ソースコードと同じツールを使ってドキュメントを書くべき」という哲学です。
Docs as Code の目的は、次のアプローチをとることでコンテンツの品質を高めることです。

  • ドキュメントのコンテンツをソースコードとして扱う
  • ソフトウェア開発における構成管理と同様に、バージョン管理する
  • コンテンツに対するテストを行う

cybozu developer network でも、この考え方を取り入れてサイトを構築しています。

サイトアーキテクチャ

以下が cybozu developer network のアーキテクチャの概要図です。

cybozu developer network のアーキテクチャの概要図

以降では、それぞれの構成要素について「なぜその技術を採用したか」を中心に紹介します。

GitHub

cybozu developer network の記事は GitHub のリポジトリで管理されています。
Docs as Code に記事の構成管理は不可欠です。

GitHub を採用した理由は以下の通りです。

  • バージョン管理が簡単にできる
  • Pull Request を利用することでレビューの仕組みが簡単に実現できる
  • 記事の校正やチェックを自動化できる

GitHub Actions

前述の「記事の校正やチェックを自動化できる」は GitHub Actions を使って実現しています。
社内には別の CI サービスを使っているチームもありますが、GitHub Actions は記事を管理する GitHub 内で完結できるため採用しています。

GitHub Actions では主に次のワークフローを実行しています。

  • textlint：表記揺れなどの文章の校正チェック
  • Markdownlint：Markdown の構文チェック
  • ESLint：サンプルコード（JavaScript）の構文チェック
  • Change page list：変更したページの一覧を PR にコメントする自作スクリプト
  • linkchecker：サイト内のリンク切れチェック

文章やサンプルコードに対して厚めにチェックすることで、レビューでは内容に関する本質的な議論に集中できる環境を目指しています。

Hugo

Markdown で書いた記事を HTML ファイルに変換する静的サイトジェネレーターには、Hugo を採用しています。
Hugo を採用している理由は次の通りです。

  • ビルドが早い
    cybozu developer network は記事数が多いため、ビルド時間が長くなりがちです。
    ほかの静的サイトジェネレーターと比較すると、Hugo はビルド時間が短く、ローカルプレビューしながら執筆するときのストレスが少なくなります。
  • ショートコードによる拡張がしやすい
    Markdown で生成できる HTML はとてもシンプルで、注意書きブロック（Callout）のような Web ページによくあるパーツを実現するには、HTML を直接書く必要があります。
    Hugo には「ショートコード」という、記事ファイル側はシンプルに書きながらも複雑な HTML を生成する仕組みが備わっています。
    そのため記事の可読性を保ちつつ、サイトを柔軟にカスタマイズできます。
  • 社内の運用実績がある
    いち早くサイボウズのヘルプサイトが、製品のヘルプサイトに Hugo を採用して運用していました [2]。
    Hugo に関するノウハウが蓄積されていることも採用の理由です。

AWS Amplify Hosting

ホスティングサービスには AWS Amplify Hosting を採用しています。
AWS Amplify Hosting（以降、AWS Amplify）を採用した理由は以下の通りです。

  • ビルドとホスティングの両方を担ってくれる
    AWS Amplify はリポジトリを接続するだけで、ビルド環境とホスティング環境の両方がシームレスに提供されます。
    また Hugo を標準サポートしているので、細かなビルドの設定が不要なことも嬉しいポイントです。
  • 他サービスに比べて料金が安い
    他のホスティングサービスには、記事を編集するユーザー数での課金が発生するサービスもあります。
    AWS Amplify はビルド回数、ビューのリクエスト数やデータ転送量で課金されるため、チームメンバーが多い場合には AWS Amplify の方が料金が安くなります。
  • AWS にすべてを集約できる
    チーム内の業務で運用しているシステムの多くは AWS 上にあります。
    AWS に集約しておくことでアカウント管理などが楽になります。
    また AWS には Lambda のようなサーバレスなアーキテクチャを実現できるサービスがあるため、将来的にサイト機能を拡張しやすいというメリットもあります。

Amazon SNS／AWS Lambda／Slack

サイトに反映したときのビルドとデプロイの結果は Slack へ通知しています。
この通知を確認することで、万が一反映に失敗したときでも気づくことが可能です。
Slack への通知の仕組みには、AWS SNS と AWS Lambda を利用しています。

AWS Amplify には、AWS SNS を利用してビルドとデプロイの結果をメール通知する機能があります。
チームの共有メールに結果を送信し確認するという運用も可能ですが、デプロイの度にメールを確認するのは面倒です。
そこで、メール通知用の AWS SNS のトピックを購読した Lambda から、普段チームで使っている Slack へ通知することにしました。

まとめ

このページでは、「cybozu developer network」で使われている技術スタックとアーキテクチャの概要を説明しました。
また、それぞれの技術の採用理由もまとめました。


記事数やアクセス数を考えると、cybozu developer network は大規模なドキュメントサイトに分類されると思います。
大規模なドキュメントサイトがどのようなアーキテクチャで運営されているかを知りたいという方に、この内容が届けば嬉しいです。

脚注

  1. WRITE THE Docs | Docs as Code ↩︎

  2. プロダクトのヘルプサイトをマークダウンに移行した話 ↩︎

Discussion