Transloadit announces complete documentation overhaul
When we started Transloadit ten years ago and began documenting our project, the docs covered uploading to S3, our jQuery SDK, resizing images, and encoding videos. Looking back, this was just a splash in the pond in comparison to what was to come.
Since then, we've grown Transloadit into the extensive company it is today, launching 17 more ways to integrate, API2, countless infra and security upgrades, and of course 71 extra features:
Input
File importing
Process
Video encoding
Audio encoding
Image manipulation
Artificial intelligence
Document processing
Output
File exporting
All these things required documentation that we gradually added on top. In good spirit of separating concerns, our developers are responsible for shipping documentation along with their newly developed features. They are also encouraged to keep unrelated things out of their Pull Requests, so that existing documentation is rarely touched.
Still, that does mean that, as it grew organically over time, our documentation could start saying contradictory things or repeat the same information several times. To counter this, once every blue moon, someone would need to digest the whole thing in search of these inconsistenties, or even fully rewrite the documentation.
We've neglected our docs for too long: the last time they were revamped was around five years ago. The old docs still contained references to our jQuery SDK, while the recommended browser integration is Uppy these days. They would also feature samples of inline Assembly Instructions, while the recommended way is to keep them in Templates these days. Taking all this into account, we knew it was time to give the documentation some tender love and care across the board. We're sorry it took so long to weed our garden again!
With that said, we are now pleased to announce that we've just completed another complete overhaul of our documentation. You can go check it out over at https://transloadit.com/docs/. Of the six main documentation sections, our most important "Integration Docs" have received a full rewrite. It took the entirety of two weeks (and many weeks before that filled with dreadful procrastination) to complete, but it was well worth it.
There are a few significant differences between the old and the neew version of the docs. While previously the documentation would:
- be categorized by difficulty (basic, advanced, 5-minute walkthrough), now it's categorized by topic, and a single Getting Started walkthrough. What's easy for some is difficult for others, and the time and effort required to complete a section of the docs have little bearing on its purpose or usefulness.
- reference the jQuery SDK as our go-to happy path, now we use Uppy's Robodog Plugin throughout.
- code samples in docs suffered from bitrot, now all code you see has actually been tested and proven to work in 2020.
- show inline Assembly Instructions, then add big disclaimers that we recommend Templates in many places, now we just use Templates in our examples from the get-go.
- feature examples with different and outdated Assembly Instructions, now all of the docs draw from a single, working face detect demo.
- include integration samples that were duplicated and hence diverged and outdated, now all those places re-use the same code that the demos also use.
We really hope the result is much more consistent, DRY, and makes for smoother onboarding. Do let us know what you think!