ドキュメンテーションはソフトウェア開発でかなり軽視されている領域のひとつだが、ようやく注意が向けられるようになってきて、@AsciidoctorやCyrille Martraire氏のDDDにインスパイアされた「Living Documentation」本など、比較的新しいツールがたくさん出てきている。APIにとって、ドキュメンテーションは不可欠なものだろう。Gregory Koberger氏は、デベロッパドキュメントをAPIとAPIダッシュボードにもっと直接つなぐためのシステムに取り組んでいる。
InfoQはReadme.ioのCEOであるGregory氏にインタビューした。彼は自らのAPIドキュメンテーションのビジョンを実現するため、この会社を作った。
InfoQ: Readme.ioの創設について、またどのように発展してきたかお話ししてくれませんか。
Gregory Koberger氏: わかりました。私のバックグラウンドはプログラマかつ設計者で、開発ツールに関心を持っています。というのも、そこには独特の設計課題があるためです。
私はドキュメントを読み書きするのにかなりの時間を費やしてきて、もっと良い方法があるはずだと思っていました。約5年前、これこそが私のやりたかったことだと決意したのですが、なかなか手をつけられないでいました。ありがたいことに、StripeやTwilioといった会社が、ドキュメントがいかに重要であるかを人々に示してくれました。そして約1年前に、私たちは始めました。
それは驚くほどうまくいきました。たくさんの人がより良いドキュメントを必要としているところで、私たちの製品と問題がぴったり合うことが、はっきりとわかりました。ドキュメンテーションについての考え方を変えていく必要があるところまでわかってきています。それは静的なものであってはいけません。だれが見ているのか、どのくらい知っているかによって、変わるべきなのです。
InfoQ: Readme.ioの背景にあるビジョンは何ですか？
GK: APIは3つの部分から成り立っています。ドキュメンテーション、ダッシュボード（デベロッパキーなどを生成するため）、そしてAPIそのものです。
私はそれらをまとめることを目指しています。APIはコードとデータについて知っています。ダッシュボードはユーザについて知っています。ドキュメンテーションはこれまで静的で、それらのことを何も知りません。
たとえば想像してみてください。ドキュメンテーションがユーザの使う言語を知っていて、コードスニペットを直接表示できたらどうでしょうか。ドキュメンテーションがユーザの具体的なエラーを受け取り、その解決を手助けできたらどうでしょうか。
InfoQ: APIをドキュメント化するとき、APIチームが直面する主な課題は何ですか？
GK: ひとつの大きな問題は、優先事項でないことです。私も含めてですが、みんなAPIをドキュメント化するのが非常に苦手です。一歩離れて、APIを使う初心者が知る必要があるものを知るのが、非常に難しいのです。
InfoQ: Readme.ioはどのように役立つのですか？ その主な機能は何ですか？
GK: 今のところは、ドキュメンテーションにフォーカスしています。コードやAPIのためのWordPressのようなものです。これはデベロッパエクスペリエンスを顧客に提供するのを、本当に簡単にしてくれます。
Readmeはフォーム、ランディングページ、チュートリアルの場所などをサポートしています。ウェブページ上でAPIをさわってみて、何が起こるか見れるようにします。GitHubからAPIドキュメンテーションを自動同期して、きれいに表示することもできます。
InfoQ: Readme.ioはSwagger UIやSlateといったオープンソースの代替品と比べてどうですか？
GK: Readme.ioの一番良いところのひとつは、デベロッパだけでなく、会社の全員が貢献できることです。もうすぐSwaggerをサポートするので、Swagger UIを簡単に置き換えられます。私たちはコミュニティがドキュメンテーションのプロセスに関わるべきだと信じています。そのため、かっこいいドラッグ＆ドロップエディタを使って、社内外のだれもが変更を提案できる、Suggested Editsという機能を備えています。
InfoQ: Readme.ioを使って作ったドキュメンテーションは既存のデベロッパポータルにデプロイできますか？
GK: Readme.ioのゴールはデベロッパハブになることです。現在のところ、既存のハブで使うことができます。将来、私たちはドキュメンテーション、ダッシュボード、サポートをまとめたいと思っています。それらがすべて同じ場所にあると、実にうまく連携します。
InfoQ: Swagger、RAML、API BlueprintといったAPI定義言語をサポートしますか？
GK: はい。現在はAPIdocと呼ぶものを使っています。もうすぐSwagger、RAML、API Blueprintのサポートをリリースする予定です。
APIを意味的にドキュメント化することによって、テキストの文章を書くのに比べて、より大きな価値を生み出します。ユーザに合わせて、SDKやサンプルコードを生成できるようになるためです。
今のところは、これらの言語はインポートに限られています。私たちはエクスポートできることも重要だと思っています。私たちはReadme.ioがデベロッパエクスペリエンスの中心になることを望んでおり、そのチャンスを活かして、さまざまなAPI会社のハブになりたいのです。
InfoQ: Code-firstやAPI-firstといった各種API開発ワークフローをどうサポートしていますか？
GK: ほとんどの場合、APIは主要なWebサイトが構築される方法をただ再現するように書かれます。これはまずいやり方です。なぜなら、何度となく、あなたはウェブサイトができないことをやるために、APIを使うためです。
そのため、ウェブサイトとは別のエンティティとして、APIを考えるのが重要だと思っています。ウェブサイトができないことがやれるよう、APIは柔軟でなくてはならないためです。
InfoQ: 実装の進化に同期し続けながらAPIについて記述するのに、一番良い方法は何ですか？
GK: APIの記述方法には、Swagger、RAML、API Blueprintなどたくさんあります。ドキュメンテーションはコードそのものに非常に近かったので、私たちはAPIdocをえらびました。これはJavadocに似ています。ドキュメントは別のファイルにあるのではなく、コードのそばにあるコメントです。私たちはGitHubから自動で同期することができます。
InfoQ: 通常のAPIチームでは、だれがAPIドキュメントを担当すべきでしょうか？
GK: もちろん全員です! これまではデベロッパだけがドキュメンテーションをしていました。しかし、APIというのは、ビジネス、マーケティング、プロダクト管理といったグループにとって非常に重要です。私たちは、デベロッパからCEOまで、全員が自分に関係のあるドキュメンテーションを更新できるようにしたいのです。
コミュニティは他の人にはない疑問やユースケースを持っているので、ものすごく重要だと思っています。
InfoQ: あなたから見て、APIドキュメンテーションと運用上のAPI管理は分けて扱うべきだと思いますか？
GK: 今、APIエコシステムに関して実に好ましいことのひとつは、特定のことを非常にうまくやる会社がたくさんあることです。大きなAPI管理会社では、すべてをやろうとするのですが、ほとんどがうまくやれていません。
私はAPI管理とドキュメンテーションは分けるべきだと思っています。ただし、それらは密に統合されるべきです。
InfoQ: 今後はどんな機能が追加されるのですか？ Readme.ioの次のバージョンはいつですか？
GK: ちょうど大きな再設計に取り組んでいるところで、1ヶ月くらいで出せるはずです。見栄えをよくするのに加えて、リファレンスガイドとサンプルを別のセクションにするつもりです。
ドキュメントを書いている人にとって、すべてがどこにあるのか、ドキュメントに何が含まれているのかが、もっと明確になります。エンドユーザにとって、どこに行けば欲しい情報が得られるのかが、もっと明確になります。
Swaggerインポートのようなものも非常に重要です。APIドキュメントを書くというプロセスをもっと自動化していきたいのです。
ドキュメンテーションというのは、たいていのデベロッパがその読み書きに時間を費やすものです。ドキュメンテーションはコードライブラリやAPIとのやりとりに使うインターフェイスであり、私はReadmeがそのやり方を変えることにワクワクしています。
Readme.ioはフリーで試すことができ、オープンソースプロジェクトにはフリーのまま使える。プロプライエタリなソフトウェアの場合、Readme.ioサブドメインで、3つのドキュメントバージョンと1人の管理ユーザを含んだ基本パッケージが、月14ドルで提供されている。独自ドメインが使えて、10人の管理ユーザをサポートするDevelopper Hubバージョンは、月59ドルで提供されている。