Transloadit anuncia una renovación completa de la documentación

Kevin van Zonneveld

Cofundador · Ámsterdam, Países Bajos ·

Cuando comenzamos Transloadit hace diez años y empezamos a documentar nuestro proyecto, la documentación abarcaba la subida a S3, nuestro SDK de jQuery (English), el redimensionado de imágenes y el encoding de videos. Visto en retrospectiva, esto fue apenas una gota en el océano en comparación con lo que vendría.

Desde entonces, hemos convertido Transloadit en la amplia empresa que es hoy, con el lanzamiento de 19 formas más de integrarse, API2, incontables mejoras de infraestructura y seguridad y, por supuesto, 93 funciones adicionales:

Entrada

Procesar

Encoding de video

Encoding de audio

Procesamiento de imágenes

Procesamiento de documentos

Inteligencia artificial

Filtrado y seguridad de archivos

Catalogación de medios

Compresión de archivos

Evaluación de código

Salida

Todo esto requería documentación que fuimos añadiendo poco a poco. Siguiendo el buen espíritu de la separación de responsabilidades, nuestros desarrolladores se encargan de entregar la documentación junto con las funciones que acaban de desarrollar. También se les anima a mantener fuera de sus Pull Requests todo lo que no esté relacionado, de modo que la documentación existente rara vez se toca.

Aun así, eso significa que, al crecer de forma orgánica con el tiempo, nuestra documentación podía empezar a decir cosas contradictorias o repetir la misma información varias veces. Para contrarrestarlo, muy de vez en cuando alguien tenía que digerirla entera en busca de estas inconsistencias, o incluso reescribir la documentación por completo.

Hemos descuidado nuestra documentación durante demasiado tiempo: la última vez que se renovó fue hace unos cinco años. La documentación antigua todavía contenía referencias a nuestro SDK de jQuery, mientras que hoy en día la integración recomendada para el navegador es Uppy. También incluía muestras de Assembly Instructions en línea, mientras que hoy en día lo recomendable es mantenerlas en Templates. Teniendo todo esto en cuenta, sabíamos que era hora de darle cariño y atención a la documentación en todos los frentes. ¡Lamentamos haber tardado tanto en volver a desmalezar nuestro jardín!

Una foto de archivo de un libro abierto con muchas pestañas a ambos lados.

Dicho esto, nos complace anunciar que acabamos de completar otra renovación integral de nuestra documentación. Puedes verla en nuestra documentación. De las seis secciones principales de la documentación, la más importante, «Documentación de integración», se ha reescrito por completo. Llevó dos semanas enteras (y muchas semanas antes de eso llenas de una procrastinación terrible), pero valió mucho la pena.

Hay algunas diferencias significativas entre la versión antigua y la nueva de la documentación. Aunque antes la documentación:

se organizaba por dificultad (básico, avanzado, recorrido de 5 minutos), ahora se organiza por tema, y un único recorrido de primeros pasos. Lo que para unos es fácil para otros es difícil, y el tiempo y el esfuerzo necesarios para completar una sección de la documentación poco tienen que ver con su propósito o su utilidad.
hacía referencia al SDK de jQuery como nuestro camino recomendado, ahora usamos el plugin Robodog de Uppy en todas partes.
las muestras de código de la documentación sufrían de bitrot, ahora todo el código que ves se ha probado de verdad y se ha comprobado que funciona en 2020.
mostraba Assembly Instructions en línea y luego añadía grandes advertencias, en muchos lugares, de que recomendamos Templates, ahora simplemente usamos Templates en nuestros ejemplos desde el principio.
incluía ejemplos con Assembly Instructions distintas y desactualizadas, ahora toda la documentación se basa en una única demo de detección de rostros (English) que funciona.
incluía muestras de integración duplicadas que, por lo tanto, divergían y quedaban desactualizadas, ahora todos esos lugares reutilizan el mismo código que también usan las demos (English).

Nota: Robodog está en desuso. Para nuevas integraciones, usa el plugin de Transloadit de Uppy (interfaz Dashboard o una interfaz personalizada).

Esperamos de verdad que el resultado sea mucho más coherente, DRY, y que facilite una incorporación más fluida. ¡Cuéntanos qué te parece!

Transloadit anuncia una renovación completa de la documentación

Entrada

Subida de archivos

Importación de archivos