LINE Developersドキュメントサイトのリデザインの話

こんにちは。LINEの開発者向けプロダクトのドキュメントを作成している、テクニカルライターのKenneth Lauです。すでにお気付きの方も多いと思いますが、2017年9月にLINE Developersサイトが大幅に更新されました。このサイトでは、LINEログインやMessaging APIのような開発者向けプロダクトに関するドキュメントや、アプリ管理用の開発者コンソールにアクセスできます。サイトの変更内容の概要については、サイトのニュース投稿「LINE Developersサイトのデザインが新しくなりました」を参照してください。

このブログ記事では、サイトを支える技術と開発者向けドキュメントの執筆プロセスに対する変更に焦点を当て、静的サイトジェネレータへの移行、この移行がドキュメント開発に与えた影響、そして今後の変更予定について述べたいと思います。まずは、LINE Developersサイトの簡単な説明から始めます。

LINE Developersサイトについて

LINE Developersサイトは、LINEログインやMessaging APIなどのプロダクトを利用する開発者向けのポータルサイトです。このサイトには、プロダクトドキュメント、LINEプラットフォームの最新情報、ユーザーの質問に答えるFAQが掲載されています。また、開発者が利用できるSDKなどのリソースをダウンロードすることもできます。

LINE Developersサイトのもう1つの構成要素は、開発者コンソールです。開発者はこのコンソールを使って、作成したアプリをLINEプラットフォームに統合するチャネルを管理します。サイトのリデザインの一環として、チャネルの作成と設定のプロセスを合理化し、以前より少ないステップで開発者向けプロダクトを使い始められるようにしました。LINEログインの実装やLINE Botの作成を試してみたい方は、LINE Developersサイトをチェックしてみてください。

WordPressから静的サイトジェネレータへ

ドキュメントサイトの今回の大幅な更新では、サイトの生成技術をWordPressから静的サイトジェネレータに変更することにしました。サイトを動的に生成するWordPressとは異なり、静的サイトジェネレータはソースファイルを静的なHTMLページに変換するだけです。このアプローチなら、ドキュメントをソースコードのように扱ってGitのワークフローを取り入れられます。WordPressは限られたコンテンツ作成者しか利用できませんでしたが、ドキュメントのコンテンツをGitHubリポジトリに格納することにより、社内のエンジニアが簡単にコンテンツを閲覧できるようになりました。

静的サイトジェネレータのもう1つの有利な点は、サイトの表示速度が速いことです。事前にビルドした静的HTMLページをロードするだけなので、動的なコンテンツ生成やデータベースクエリが不要です。また、WordPressインスタンスの維持に関わる管理負荷から解放され、サイトのセキュリティを保つため、セキュリティパッチを定期的にインストールするなどの作業がなくなりました。

今日、さまざまな静的サイトジェネレータを利用できますが、私たちはMiddlemanを使うことにしました。高度なカスタマイズが可能で、私たちのニーズに応えられると感じたからです。次のセクションでは、LINE DevelopersサイトにどのようにしてMiddlemanを組み込んだか説明します。

Middlemanを使う

Middlemanはオープンソースの静的サイトジェネレータで、Rubyで構築されており、活発な開発者コミュニティがあります。Middlemanでは、Markdown記法を使って再利用可能なコンテンツや複数のレイアウトを開発し、多言語で表示することができます。ここでは、LINE DevelopersサイトにどのようにしてMiddlemanを組み込んだか、詳細の一部を説明します。

RedcarpetでMarkdownをレンダリングする

私たちはMarkdownでドキュメントを書き、Redcarpetでその内容を解析してHTMLにレンダリングしています。Markdownは軽量で判読可能なマークアップ言語ですが、標準外の表を作成するなどの特定の状況で、Redcarpetでは私たちの要件を満たせないことがわかりました。このような場合の解決策として、Redcarpetのカスタマイズ機能を使ってカスタムのMarkdown要素を作成しました。たとえば、表見出しを一番上の行ではなく左の列に設定するために、カスタム要素を作成しました。

|>|
|| **Superclass** | `NSObject` |
|| **Declared in** | LineSDKAPI.h |
|>|

ERBテンプレート

ERB(Embedded RuBy)テンプレートエンジンを使って、記事、ニュース投稿、FAQ項目、およびAPIリファレンスの各ページにふさわしいテンプレートを作成しました。Middlemanの場合は、さまざまな変数とヘルパーメソッドを動的なERBテンプレートに追加し、静的HTMLページとして出力できます。テンプレートはlayoutsフォルダーに格納し、必要に応じて特定のMarkdownまたはHTMLファイルに適用できるようにしました。

YAMLデータファイル

YAMLデータファイルを使って、サイトのトップページとナビゲーションバーの特定のコンテンツを管理しています。データファイルなら、HTMLファイルを直接操作する代わりに、読みやすいフォーマットで効率的に値を編集できます。たとえば、以下のサイドバーの内容はYAMLデータファイルのデータを抽出して生成されています。

sidebar_title_en: "iOS SDK"
menu_items: 
  - title_en: "Guides"
    url:
    subpages:
    - title_en: "Overview"
      url: "/docs/ios-sdk/overview"
      subpages: []
    - title_en: "Logging out users"
      url: "/docs/ios-sdk/logging-out-users"
      subpages: []
    - title_en: "Getting user profiles"
      url: "/docs/ios-sdk/getting-user-profiles"
      subpages: []
    - title_en: "Managing access tokens"
      url: "/docs/ios-sdk/managing-access-tokens"
      subpages: []

再利用可能なコンテンツ

サイトの各所でコンテンツを再利用するため、リポジトリのpartialsフォルダーにMarkdownファイルを作成しました。これらのファイルのコンテンツは、partialメソッドを使うかドキュメントのYAML Frontmatterにファイル名を指定して、複数のページで利用できます。私たちの実装では、APIリファレンスドキュメントやエラーの説明などをパーシャルファイルに含め、複数のページで再利用できるようにしました。以下の例では、partialメソッドを使ってエラーレスポンスの表をドキュメントに記載しています。

ローカリゼーション

リデザインの目標の1つは、複数言語のサポートをサイトに追加することでした。以前のサイトでは英語でしかドキュメントを提供していなかったのですが、新サイトでは日本語を追加しました。複数言語のサイトを作成するため、Middlemanの国際化機能を利用しました。enjaのYAMLファイルで特定のキーに各言語の値をマップし、テンプレート内でi18nヘルパーメソッドを使ってそれらのキーを参照します。たとえば、私たちが設定したdocumentationキーは、英語では「Documentation」に、日本語では「ドキュメント」に対応します。

Middlemanを使うと、英語と日本語のページに対してローカライズされたパスも作成できます。英語をデフォルトの言語に設定し、ドキュメントのファイル名にjaを追加することで、Middlemanがローカライズされたパスを生成するようにしました。

GitHubにドキュメントリポジトリを作成する

前セクションまでの作業が終わり、WordPressからMiddlemanへの移行が完了しました。これで、ソースファイルをGitHubのリポジトリに格納して管理できます。LINEのエンジニアは全員GitHub Enterpriseへのアクセス権を持ち、日常的に使用しているので、誰もがドキュメントリポジトリにイシューやプルリクエストを作成できます。ライターの立場から見ると、GitHubベースのワークフローに切り替え、ドキュメントの作成フローをプログラムの開発フローに近づけることによって、エンジニアと協働しやすくなりました。ドキュメントをGitHub Enterpriseのリポジトリに格納したため、エンジニアがコードレビューをするように、プルリクエストを使ってドキュメントをレビューできます。

ビルドプロセスでJenkinsを使用する

Jenkinsを使ってテストとビルドのプロセスを自動化しました。執筆者がプルリクエストを作成すると、Jenkinsは自動的にチェックを実行し、サイトがビルド可能かどうか確認します。その後でレビュー担当者がプルリクエストをレビューし、問題がなければmasterブランチにマージします。マージをトリガーにJenkinsはもう1つのスクリプトを実行し、Middlemanサイトをビルドしてベータ環境にデプロイします。ベータ環境での最終確認の後、実稼働環境にサイトをデプロイします。

Docs-as-codeアプローチ

静的サイトジェネレータの導入により、他のエンジニアが使っているGitのワークフローをドキュメント開発に採用できました。そしてこのアプローチのおかげで、ライターが開発チームとより密接に協働できるようになりました。ドキュメントリポジトリの可視性が高まった今、外部向けドキュメントを充実させるため、社内のエンジニアにドキュメントリポジトリへの貢献を奨励していこうと考えています。究極的には、このアプローチによってドキュメント開発のイテレーションの速度が上がり、より高い品質の開発者向けドキュメントの提供が可能になるでしょう。

将来の計画

今回のサイト更新は、開発者ドキュメントの向上の開始点に過ぎません。将来は、さらにプロセスを自動化してドキュメントの品質を上げ、新しいコンテンツをもっと短期間で公開していきたいと考えています。ここでいう自動化には、リンクの自動検証、スタイルリンターの追加、APIドキュメントの自動生成などがあります。最近はサイトに検索機能を追加しましたが、ナビゲーション機能も向上させ、ユーザーが必要なコンテンツを見つけやすくしたいです。

コンテンツに関しては、もっと頻繁なリリースと更新を行い、ユーザーがLINEの開発者向けプロダクトを使って便利なアプリを作るための情報を提供していきますので、ご期待ください。

LINEアプリで以下のQRコードを読み込んでLINE Developers公式アカウントを友だち追加すると、LINE Developersサイトの最新情報を受け取れます。

フィードバックを送信できるフォームもサイト内に設置しましたので、ご意見やご要望をお寄せいただけると幸いです。

終わりに

LINE Developersサイトを支える技術について詳しくは、以下の動画と資料をご覧ください。LINE DEVELOPER DAY 2017で、ドキュメントサイトのテクニカルリードであるMark Serranoが発表した内容です。


また、高品質なドキュメントの作成やドキュメント作成のツールチェインの向上にご興味がある方を募集しています。詳しくは、「Careers@LINE」ページで現在募集中の職種をご覧ください。

Related Post