Platformこんにちは。Developersサイトが大幅に更新されました。APIのような開発者向けプロダクトに関するドキュメントや、アプリ管理用の開発者コンソールにアクセスできます。Developersサイトのデザインが新しくなりました」を参照してください。このブログ記事では、サイトを支える技術と開発者向けドキュメントの執筆プロセスに対する変更に焦点を当て、静的サイトジェネレータへの移行、この移行がドキュメント開発に与えた影響、そして今後の変更予定について述べたいと思います。Developersサイトの簡単な説明から始めます。APIなどのプロダクトを利用する開発者向けのポータルサイトです。このサイトには、プロダクトドキュメント、LINEプラットフォームの最新情報、ユーザーの質問に答えるFAQが掲載されています。開発者が利用できるSDKなどのリソースをダウンロードすることもできます。Developersサイトのもう1つの構成要素は、開発者コンソールです。開発者はこのコンソールを使って、作成したアプリをLINEプラットフォームに統合するチャネルを管理します。サイトのリデザインの一環として、チャネルの作成と設定のプロセスを合理化し、以前より少ないステップで開発者向けプロダクトを使い始められるようにしました。Developersサイトをチェックしてみてください。WordPressから静的サイトジェネレータへドキュメントサイトの今回の大幅な更新では、サイトの生成技術をWordPressから静的サイトジェネレータに変更することにしました。サイトを動的に生成するWordPressとは異なり、静的サイトジェネレータはソースファイルを静的なHTMLページに変換するだけです。このアプローチなら、ドキュメントをソースコードのように扱ってGitのワークフローを取り入れられます。WordPressは限られたコンテンツ作成者しか利用できませんでしたが、ドキュメントのコンテンツをGitHubリポジトリに格納することにより、社内のエンジニアが簡単にコンテンツを閲覧できるようになりました。静的サイトジェネレータのもう1つの有利な点は、サイトの表示速度が速いことです。事前にビルドした静的HTMLページをロードするだけなので、動的なコンテンツ生成やデータベースクエリが不要です。WordPressインスタンスの維持に関わる管理負荷から解放され、サイトのセキュリティを保つため、セキュリティパッチを定期的にインストールするなどの作業がなくなりました。今日、さまざまな静的サイトジェネレータを利用できますが、私たちはMiddlemanを使うことにしました。高度なカスタマイズが可能で、私たちのニーズに応えられると感じたからです。DevelopersサイトにどのようにしてMiddlemanを組み込んだか説明します。Middlemanを使うMiddlemanはオープンソースの静的サイトジェネレータで、Rubyで構築されており、活発な開発者コミュニティがあります。Middlemanでは、Markdown記法を使って再利用可能なコンテンツや複数のレイアウトを開発し、多言語で表示することができます。DevelopersサイトにどのようにしてMiddlemanを組み込んだか、詳細の一部を説明します。RedcarpetでMarkdownをレンダリングする私たちはMarkdownでドキュメントを書き、Redcarpetでその内容を解析してHTMLにレンダリングしています。Markdownは軽量で判読可能なマークアップ言語ですが、標準外の表を作成するなどの特定の状況で、Redcarpetでは私たちの要件を満たせないことがわかりました。このような場合の解決策として、Redcarpetのカスタマイズ機能を使ってカスタムのMarkdown要素を作成しました。表見出しを一番上の行ではなく左の列に設定するために、カスタム要素を作成しました。RuBy)テンプレートエンジンを使って、記事、ニュース投稿、FAQ項目、およびAPIリファレンスの各ページにふさわしいテンプレートを作成しました。Middlemanの場合は、さまざまな変数とヘルパーメソッドを動的なERBテンプレートに追加し、静的HTMLページとして出力できます。テンプレートはlayoutsフォルダーに格納し、必要に応じて特定のMarkdownまたはHTMLファイルに適用できるようにしました。YAMLデータファイルYAMLデータファイルを使って、サイトのトップページとナビゲーションバーの特定のコンテンツを管理しています。データファイルなら、HTMLファイルを直接操作する代わりに、読みやすいフォーマットで効率的に値を編集できます。以下のサイドバーの内容はYAMLデータファイルのデータを抽出して生成されています。[]再利用可能なコンテンツサイトの各所でコンテンツを再利用するため、リポジトリのpartialsフォルダーにMarkdownファイルを作成しました。Frontmatterにファイル名を指定して、複数のページで利用できます。私たちの実装では、APIリファレンスドキュメントやエラーの説明などをパーシャルファイルに含め、複数のページで再利用できるようにしました。以下の例では、partialメソッドを使ってエラーレスポンスの表をドキュメントに記載しています。ローカリゼーションリデザインの目標の1つは、複数言語のサポートをサイトに追加することでした。以前のサイトでは英語でしかドキュメントを提供していなかったのですが、新サイトでは日本語を追加しました。複数言語のサイトを作成するため、Middlemanの国際化機能を利用しました。enとjaのYAMLファイルで特定のキーに各言語の値をマップし、テンプレート内でi18nヘルパーメソッドを使ってそれらのキーを参照します。私たちが設定したdocumentationキーは、英語では「Documentation」に、日本語では「ドキュメント」に対応します。Middlemanを使うと、英語と日本語のページに対してローカライズされたパスも作成できます。英語をデフォルトの言語に設定し、ドキュメントのファイル名にjaを追加することで、Middlemanがローカライズされたパスを生成するようにしました。GitHubにドキュメントリポジトリを作成する前セクションまでの作業が終わり、WordPressからMiddlemanへの移行が完了しました。これで、ソースファイルをGitHubのリポジトリに格納して管理できます。Enterpriseへのアクセス権を持ち、日常的に使用しているので、誰もがドキュメントリポジトリにイシューやプルリクエストを作成できます。ライターの立場から見ると、GitHubベースのワークフローに切り替え、ドキュメントの作成フローをプログラムの開発フローに近づけることによって、エンジニアと協働しやすくなりました。Enterpriseのリポジトリに格納したため、エンジニアがコードレビューをするように、プルリクエストを使ってドキュメントをレビューできます。ビルドプロセスでJenkinsを使用するJenkinsを使ってテストとビルドのプロセスを自動化しました。執筆者がプルリクエストを作成すると、Jenkinsは自動的にチェックを実行し、サイトがビルド可能かどうか確認します。その後でレビュー担当者がプルリクエストをレビューし、問題がなければmasterブランチにマージします。マージをトリガーにJenkinsはもう1つのスクリプトを実行し、Middlemanサイトをビルドしてベータ環境にデプロイします。ベータ環境での最終確認の後、実稼働環境にサイトをデプロイします。Docs-as-codeアプローチ静的サイトジェネレータの導入により、他のエンジニアが使っているGitのワークフローをドキュメント開発に採用できました。このアプローチのおかげで、ライターが開発チームとより密接に協働できるようになりました。ドキュメントリポジトリの可視性が高まった今、外部向けドキュメントを充実させるため、社内のエンジニアにドキュメントリポジトリへの貢献を奨励していこうと考えています。究極的には、このアプローチによってドキュメント開発のイテレーションの速度が上がり、より高い品質の開発者向けドキュメントの提供が可能になるでしょう。今回のサイト更新は、開発者ドキュメントの向上の開始点に過ぎません。将来は、さらにプロセスを自動化してドキュメントの品質を上げ、新しいコンテンツをもっと短期間で公開していきたいと考えています。ここでいう自動化には、リンクの自動検証、スタイルリンターの追加、APIドキュメントの自動生成などがあります。最近はサイトに検索機能を追加しましたが、ナビゲーション機能も向上させ、ユーザーが必要なコンテンツを見つけやすくしたいです。コンテンツに関しては、もっと頻繁なリリースと更新を行い、ユーザーがLINEの開発者向けプロダクトを使って便利なアプリを作るための情報を提供していきますので、ご期待ください。Developersサイトの最新情報を受け取れます。フィードバックを送信できるフォームもサイト内に設置しましたので、ご意見やご要望をお寄せいただけると幸いです。Developersサイトを支える技術について詳しくは、以下の動画と資料をご覧ください。Serranoが発表した内容です。docs」また、高品質なドキュメントの作成やドキュメント作成のツールチェインの向上にご興味がある方を募集しています。詳しくは、「Careers@LINE」ページで現在募集中の職種をご覧ください。Developers日本語English。