Transloadit のドキュメント全面改訂のお知らせ
Transloadit を10 年前に立ち上げ、プロジェクトのドキュメントを書き始めた頃、ドキュメントで扱っていたのは、S3 へのアップロード、私たちの jQuery SDK (English)、画像のリサイズ、動画のエンコードでした。振り返ると、その後の展開に比べれば、ほんのささやかな始まりでした。
それ以来、Transloadit を現在の規模にまで成長させる中で、20 種類の連携方法を追加し、API2 を公開し、数え切れないほどのインフラとセキュリティの改善を行い、そしてもちろん、95 個の追加機能も提供してきました:
入力
処理
出力
こうした追加や改善にはすべてドキュメントが必要で、その都度書き足してきました。関心の分離という考え方に沿って、開発者は新機能と一緒にドキュメントも公開する責任を担っています。また、プルリクエストに無関係な変更を含めないよう推奨しているため、既存のドキュメントが修正されることはほとんどありません。
ただし、このように時間とともに少しずつ増えていくと、説明に矛盾が生じたり、同じ情報が何度も繰り返されたりすることがあります。それを防ぐには、たまに誰かが全体を読み込んで不整合を探し、場合によってはドキュメント全体を書き直す必要があります。
ドキュメントを長い間放置しすぎてしまいました。前回の刷新は約 5 年前のことです。現在推奨しているブラウザー向け連携は Uppy なのに、古いドキュメントには jQuery SDK への言及が残っていました。また、現在は Template に保存する方法を推奨しているにもかかわらず、インラインの Assembly Instructions の例も掲載していました。こうした状況から、ドキュメント全体を丁寧に見直す時期だと判断しました。再び手入れに取りかかるまで、長くお待たせしてしまい申し訳ありません!

そして今回、ドキュメントの全面改訂が再び完了しましたので、お知らせします。私たちのドキュメントでご覧いただけます。主要な 6 つのセクションのうち、最も重要な「連携ドキュメント」はすべて書き直しました。完了まで丸 2 週間(その前には、気が重くて先延ばしにしていた何週間もの期間)がかかりましたが、それだけの価値はありました。
旧版と新版のドキュメントには、いくつかの大きな違いがあります。これまでの構成や内容を、次のように変更しました。
- 難易度別の分類(基本、上級、5 分のチュートリアル)から、現在はトピック別の分類と、導入用のチュートリアル 1 つに変更しました。簡単と感じるか難しいと感じるかは人それぞれです。また、各セクションの完了に必要な時間や労力は、その目的や有用性とはあまり関係ありません。
- 標準的な連携方法として jQuery SDK を紹介していましたが、現在は全体を通して Uppy の Robodog Plugin を使用しています。
- コード例は古くなって動かなくなっていましたが、現在は掲載しているコードをすべて実際にテストし、2020 年時点で動作することを確認しています。
- インラインの Assembly Instructions を示した後、Template を推奨するという大きな注意書きを各所に載せていましたが、現在は例の最初から Template を使用しています。
- 例ごとに異なる古い Assembly Instructions を使っていましたが、現在はすべてのドキュメントで、動作確認済みの同じ顔検出デモ (English)を基にしています。
- 連携のサンプルが重複し、それぞれに違いが生じて古くなっていましたが、現在はすべての箇所でデモ (English)と同じコードを再利用しています。
注:Robodog は非推奨になりました。新規の連携には、Uppy の Transloadit plugin(Dashboard UI またはカスタム UI)を使用してください。
今回の改訂によって、一貫性と DRY の原則により忠実な内容となり、導入をよりスムーズに進めていただけることを願っています。ぜひご感想をお聞かせください!
