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.
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!
Share your Transloadit project to earn $300
We love seeing how our community uses Transloadit. Tweet @transloadit to get your proposal approved, share what you’ve built in the form of a blog post or a tutorial on your website, and earn a $300 Gift certificate of your choice as well as a full year of the Startup Plan, at no cost after you publish.
Follow us on Twitter:Follow @transloadit
We're SO STOKED to announce the Transloadit Community Plan! 🎉🎉🎉 Unlimited uploading, importing and exporting, 5GB of encoding/month, and access to 50 different file conversion features for all.— 🤖 Transloadit (@transloadit) July 2, 2020
Best part? It's free. Forever. 🤑 Find out more https://t.co/zXWLi3Xa0G pic.twitter.com/DlY5xz1mPG