Transloadit anuncia reformulação completa da documentação

Kevin van Zonneveld

Cofundador · Amsterdã, Países Baixos ·

Quando começamos a Transloadit há dez anos e passamos a documentar nosso projeto, a documentação abrangia o upload para o S3, nosso SDK para jQuery (English), o redimensionamento de imagens e a codificação de vídeos. Olhando para trás, isso era só uma gota no oceano em comparação com o que estava por vir.

Desde então, transformamos a Transloadit na empresa ampla que ela é hoje, lançando 19 novas formas de integração, a API2, inúmeras melhorias de infraestrutura e de segurança e, claro, 95 recursos extras:

Entrada

Processamento

Codificação de vídeo

Codificação de áudio

Processamento de imagens

Processamento de documentos

Inteligência artificial

Filtragem de arquivos e segurança

Catalogação de mídia

Compressão de arquivos

Avaliação de código

Saída

Exportação de arquivos

Smart CDN

Tudo isso exigiu documentação, que fomos acrescentando aos poucos. No bom espírito da separação de responsabilidades, nossos desenvolvedores são responsáveis por entregar a documentação junto com os recursos que acabaram de desenvolver. Eles também são incentivados a deixar assuntos não relacionados fora dos seus pull requests, de modo que a documentação existente raramente é alterada.

Ainda assim, isso significa que, à medida que crescia organicamente ao longo do tempo, nossa documentação podia começar a dizer coisas contraditórias ou a repetir a mesma informação várias vezes. Para contornar isso, muito de vez em quando alguém precisava digerir tudo em busca dessas inconsistências, ou até reescrever a documentação por completo.

Deixamos nossa documentação de lado por tempo demais: a última reformulação foi há cerca de cinco anos. A documentação antiga ainda continha referências ao nosso SDK para jQuery, enquanto hoje em dia a integração recomendada para navegadores é o Uppy. Ela também trazia exemplos de Assembly Instructions inline, enquanto hoje a forma recomendada é mantê-las em Templates. Levando tudo isso em conta, sabíamos que era hora de dar à documentação um pouco de carinho e atenção de ponta a ponta. Pedimos desculpas por termos demorado tanto para cuidar do nosso jardim de novo!

Uma foto de banco de imagens de um livro aberto com muitos marcadores dos dois lados.

Dito isso, temos o prazer de anunciar que acabamos de concluir mais uma reformulação completa da nossa documentação. Você pode conferi-la em nossa documentação. Das seis seções principais da documentação, a mais importante, a “Documentação de integração”, foi totalmente reescrita. Foram duas semanas inteiras de trabalho (e muitas semanas antes disso repletas de uma terrível procrastinação) para concluir, mas valeu muito a pena.

Existem algumas diferenças significativas entre a versão antiga e a nova da documentação. Enquanto antes a documentação:

era categorizada por dificuldade (básico, avançado, passo a passo de 5 minutos), agora ela é categorizada por tema, com um único tutorial de primeiros passos. O que é fácil para uns é difícil para outros, e o tempo e o esforço necessários para concluir uma seção da documentação pouco têm a ver com o seu propósito ou utilidade.
usava o SDK para jQuery como referência para o nosso caminho padrão de integração sem complicações, agora usamos o plugin Robodog do Uppy em toda a documentação.
tinha exemplos de código que sofriam com a obsolescência gradual, agora todo o código que você vê foi realmente testado e comprovadamente funciona em 2020.
mostrava Assembly Instructions inline e depois acrescentava grandes avisos de que recomendamos Templates em vários lugares, agora simplesmente usamos Templates nos nossos exemplos desde o início.
trazia exemplos com Assembly Instructions diferentes e desatualizadas, agora toda a documentação se baseia em uma única demonstração de detecção de rostos (English) que funciona.
incluía exemplos de integração duplicados, que por isso divergiram e ficaram desatualizados, agora todos esses lugares reutilizam o mesmo código que as demonstrações (English) também usam.

Observação: o Robodog foi descontinuado. Para novas integrações, use o plugin Transloadit do Uppy (com a interface Dashboard ou uma interface personalizada).

Esperamos sinceramente que o resultado seja muito mais consistente e DRY, e que torne a integração inicial mais tranquila. Conte para a gente o que você achou!