Transloadit annonce une refonte complète de sa documentation

Lorsque nous avons lancé Transloadit il y a dix ans EN (English) et commencé à documenter notre projet, la documentation couvrait⁠ le téléversement vers S3, notre SDK jQuery EN (English), le redimensionnement d’images et l’encodage de vidéos. Avec le recul, ce n’était qu’une goutte d’eau par rapport à ce qui allait suivre.

Depuis, nous avons fait de Transloadit l’entreprise d’envergure qu’elle est aujourd’hui, en lançant 19 façons supplémentaires de l’intégrer, API2, d’innombrables améliorations de l’infrastructure et de la sécurité, et bien sûr 95 fonctionnalités supplémentaires EN (English) :

Tous ces éléments nécessitaient une documentation, que nous avons ajoutée au fur et à mesure. Pour respecter le principe de séparation des responsabilités, nos développeurs doivent livrer la documentation avec les fonctionnalités qu’ils créent. Nous les encourageons aussi à ne pas inclure de changements sans rapport dans leurs demandes de fusion, si bien que la documentation existante est rarement modifiée.

Cela signifie toutefois qu’au fil de son évolution, notre documentation pouvait finir par contenir des contradictions ou répéter plusieurs fois les mêmes informations. Pour y remédier, il fallait, de temps à autre, que quelqu’un passe l’ensemble en revue à la recherche de ces incohérences, voire réécrive entièrement la documentation.

Nous avons négligé notre documentation trop longtemps : sa dernière refonte remontait à environ cinq ans. L’ancienne documentation faisait encore référence à notre SDK jQuery, alors qu’Uppy est désormais la solution recommandée pour l’intégration dans le navigateur. Elle présentait aussi des exemples avec des Assembly Instructions intégrées directement au code, alors que nous recommandons désormais de les conserver dans des Templates. Face à ce constat, nous savions qu’il était temps de prendre soin de l’ensemble de notre documentation. Nous sommes désolés d’avoir tant tardé à désherber de nouveau notre jardin !

Nous avons donc le plaisir d’annoncer que nous venons d’achever une nouvelle refonte complète de notre documentation. Vous pouvez découvrir le résultat dans notre documentation. Parmi ses six sections principales, la plus importante, « Documentation d’intégration », a été entièrement réécrite. Ce travail a pris deux semaines entières (précédées de nombreuses semaines de pénible procrastination), mais il en valait largement la peine.

L’ancienne et la nouvelle version de la documentation présentent plusieurs différences importantes. Auparavant, la documentation :

• était classée par difficulté (niveau de base, avancé, guide de 5 minutes) ; désormais, elle est classée par sujet, avec un seul guide de prise en main. Ce qui est facile pour certains est difficile pour d’autres, et le temps et les efforts nécessaires pour parcourir une section de la documentation ont peu de rapport avec son objectif ou son utilité.
• présentait le SDK jQuery comme notre parcours recommandé ; désormais, nous utilisons le plugin Robodog d’Uppy partout.
• contenait des exemples de code devenus obsolètes ; désormais, tout le code que vous voyez a réellement été testé et son bon fonctionnement a été vérifié en 2020.
• présentait des Assembly Instructions intégrées directement au code, puis ajoutait de longs avertissements indiquant que nous recommandions les Templates à de nombreux endroits ; désormais, nous utilisons simplement des Templates dans nos exemples dès le départ.
• proposait des exemples avec des Assembly Instructions différentes et obsolètes ; désormais, toute la documentation s’appuie sur une seule démo fonctionnelle de détection de visages EN (English).
• incluait des exemples d’intégration dupliqués, qui avaient donc divergé et étaient devenus obsolètes ; désormais, tous ces endroits réutilisent le même code que les démos EN (English).

Remarque : Robodog est désormais déprécié. Pour les nouvelles intégrations, utilisez le plugin Transloadit⁠ d’Uppy (avec l’interface Dashboard ou une interface personnalisée).

Nous espérons vraiment que le résultat est beaucoup plus cohérent, respecte mieux le principe DRY⁠ et facilite la prise en main. N’hésitez pas à nous faire part de votre avis !