シェア:
){kind=small}
ファビアンはVonageのデベロッパー・エクスペリエンス・チームの一員でした。オープンソース、機械学習、コーヒーをこよなく愛する情熱的なソフトウェア・エンジニア。 私たちのドキュメントをより良いものにするために働いていないときは、サイクリング、読書、クラブ・ナシオナル・デ・フットボールの応援をしています。
駅に到着：APIドキュメンテーションプラットフォームの進化
3年前、私たちのドキュメンテーション・プラットフォームが誕生した。私たちは、その時に行ったいくつかの設計上の決定が今に影響を与えることになるとは知りませんでした。例えば、私たちは、JekyllやMiddlemanなどのマークダウンファイル用の静的サイトジェネレータではなく、Ruby on Railsを使用してオープンソースのウェブアプリケーションを構築することを選択しました。
Railsのようなウェブ・フレームワークは完璧な選択だった。
3年前、私たちは、めまぐるしく変化するAPI企業として、私たちのプロジェクトのスコープが最終的にどのようなものになるのか知りませんでした。私たちのドキュメンテーション・プラットフォームがどこまで成長したかを想像するのは難しいし、将来どうなるかを想像するのはさらに難しい。
現在に至って、プラットフォーム周りのツールは大幅に増加した。自動スペルチェック、国際化、API仕様の妥当性やスタイルのチェックなど、リストは増え続けている。
このプラットフォームは創業以来 Vonage API 開発者.Vonage API DeveloperはNexmo Developerとして誕生し、誕生から数年の間に、世界的なユニファイドクラウドコミュニケーションのリーディングプロバイダーであるVonageの一部となりました。その結果、このプラットフォームに対する要求と期待は、指数関数的に増大したように思われる。
プラットフォームの進化の物語はこれで終わりではなかった。
半年前、ドキュメント・サイトに使っていたツールが寿命を迎えたため、社内の別のプロダクト・チームが私たちに連絡してきました。彼らは Vonage API Developer プラットフォームのシンプルなコピーに移行することに興奮していましたが、残念なことに、それを使用する準備ができていませんでした。プラットフォームのコードと Vonage API Developer のドキュメンテーションが同じリポジトリにあるだけでなく、いくつかのページや機能は、その製品ラインに固有の他の形式のコンテンツをサポートするように構築されていませんでした。
単一のモノリスRailsアプリケーションに課されるツールのニーズが複雑化したことと、Vonageのさまざまな製品ラインによるプラットフォームの採用への関心が高まったことが相まって、私たちはより良い代替手段を探すことになりました。
そうしてたどり着いたのが 駅.
過去数ヶ月間、私たちは散文とプラットフォームのコードを分離しました。コンテンツにとらわれないプラットフォームへとリファクタリングし、多くのコンテンツ形式やメディアをサポートし、ビジネス全体の他のチームに力を与えることができるようにした。
Station はプラットフォームツールです。いくつかの設定ファイルを定義し、コンテンツが存在するパスを設定することで、ターミナルからのコマンドひとつでウェブサイトをインスタンス化することができます。
箱から出してすぐに次のことができるように作られている：
テキスト主体のウェブサイトを素早く作成するソリューション
プログラミングの専門知識に関係なく、誰もが合理的な方法でコンテンツに貢献できる能力
設定ファイルのセットにより、各サイトのニーズに合わせて高度にカスタマイズ可能
Stationの核心は、高度にカスタマイズされたRuby on Rails（およびWebpack）アプリケーションをRuby Gem（Rubyプログラミング言語による再利用可能なソフトウェアパッケージ）にバンドルしたものです。経験豊富な Rails 開発者にとっては、馴染みのあるものに感じられるでしょう。Rails を知らない人にとっては、Station を使ったサイトを運営したりコンテンツを投稿したりするためにフレームワークのニュアンスを学ぶ必要はないでしょう。
メディアリッチなコンテンツのレンダリング、OpenAPI仕様ファイル、ステップバイステップのチュートリアル、カスタム作成されたウェブページ、ユースケース、フィードバックの提供、コンテンツの検索などなど。
コンテンツだけでなく、サイトのほとんどの部分を設定ファイルでカスタマイズすることができます。以下のスニペットは、サイトのヘッダーとフッターの設定ファイルに対応しています。
こうしてページ上にレンダリングされる。
どのようなコンテンツ・サイトにも対応する堅牢なプラットフォームを構築し、現在2つのチームのドキュメント・サイトを支えているのは喜ばしいことだが、まだ誰もが完全に利用できるわけではない。
オープンソースとはいえ、このgemはGithubのパッケージ登録を使ってリリースされており、リリースはまだ一般公開されていません。しかし、近いうちにパブリックなv1.0をリリースする予定で、Rubygemsを通じて誰でも利用できるようになります。
次回の投稿では、私たちのドキュメントとOpen API仕様を一流に保つために構築した、上記のツールのいくつかについてお話します。