nango VS diataxis-documentation-framework

2 min demo video: https://www.loom.com/share/d04c67b47e284e86b91b4b99fba548ec

SaaS engineering teams face a tough choice: they can build each integration in-house from scratch, which gives them full control but takes a lot of time and maintenance effort. Or they can use pre-built solutions, which are fast and easy but less flexible and might not fulfill all customer needs.

Nango combines the best of both worlds. We let you quickly ship custom integrations without building complex infrastructure or diving deep into the quirks of each API. You control the business logic, data models, and customer-specific configurations, like custom field mappings. We handle (O)Auth and run your integrations reliably in production.

Under the hood, your integrations run as typescript “lambdas” on Nango. A typical integration has 3-5 lambdas of 20-50 lines of code each. These lambdas live inside your git repo, are version-controlled with the rest of your app, and get deployed to Nango with a CLI (https://docs.nango.dev/understand/core-concepts).

Our runtime has a built-in scheduler for continuous background syncs, monitoring to know if your integrations run as expected, detailed logging of everything that happens in Nango, and pre-built infrastructure to deal with (O)auth, retries, rate-limit handling, webhook floods, data caching, de-duplication, etc. More here: https://docs.nango.dev/understand/architecture

We have found that ChatGPT and Copilot let you build integrations on Nango very fast without having to learn each API’s intricacies. LLMs are great at figuring out which endpoint to use, what parameters it takes, etc. Paired with our runtime, this lets you build complex, high-scale integrations in hours instead of weeks.

We’ve put a ton of effort into dealing with API complexities, so you don’t have to. Even integrations that looked simple at first ended up forcing us to extend our infra to deal with their quirks and gotchas.

For example, we had to figure out 100+ different OAuth implementations (see https://www.nango.dev/blog/why-is-oauth-still-hard and https://news.ycombinator.com/item?id=35713518). We had to deal with a half-dozen non-standard auth methods (Github apps, Stripe apps, Netsuite, etc.), expiring webhooks, ways to deal with data dependencies, weird pagination methods, API keys that change with every API call, dozens of different ways to register for webhooks, etc. It’s a constantly moving target, but it is a challenge we have come to love, and we think the approach makes sense: we specialize in finicky details that vary from API to API—you specialize in making your product great and offering more integrations to your users.

The fastest way to see Nango in action is with our interactive demo here (no signup required): https://app.nango.dev/hn-demo

Back in August I queried [1] your usage of "open source" while not being an open source project (ELv2 licensed). It looks like you're no longer describing yourself as "100% Open Source" which is good but you still label yourself as open source in the repo readme and still refer to yourself as open source on the website. Do you intend to keep labelling yourself as open source or is that something you're moving away from?

[1] https://github.com/NangoHQ/nango/issues/900

https://www.nango.dev founder here.

I think the biggest difference is that Nango lets you customize & extend the unified APIs on the platform.

Usually unified APIs mitigate their limited catalog with passthrough/proxy requests. But this is a partial solution, since you go back to having a lot of integration logic in your code base.

With Nango these customizations live in the unified API itself and benefit from all the infrastructure available there (OAuth, rate-limit handling, pagination, de-duplication of records, etc.).

Definitely a difficult problem you're taking on here, but I don't see anything specific to LLMs here? How or why are you marketing towards LLMs?

How do you compare to the larger players here already Nango[0] and Merge[1] ?

I'm curious how you're thinking about data access / staleness? It's great that you're handling the oauth dance, but does that mean every end user of the product has to auth every product they interface with or are you handling this all at the super admin / enterprise level?

Right now I think there's too much emphasis on the "data loading" aspect of LLMs. I expect to see a swing back into using 3rd party API's SDKs. Interested to hear your thoughts on the Google API, it's absolutely massive and trying to shoehorn that into a unified API scares me.

The only real player that I could see to launch something like this and be successful is Okta.

[0] - https://github.com/NangoHQ/nango

What you describe is pretty much what we build at https://github.com/NangoHQ/nango, would be great to incorporate your learnings :)

You can mix & match these components as needed to build your own custom integrations fast. In brief, we are building an open-source platform for product integrations.

Perhaps it could be restructured to separate out the howto from the explanation to serve the reader’s intended use at the time as described here: https://diataxis.fr

Create an organized repository for regularly updated documentation, making it easy to access important information.

Such integration capabilities really help push the developer productivity, whether that's in single-project workspaces or monorepos. Juri also dives deeper into efforts from the team to provide high quality educational content around Nx and its capabilities. The Nx docs have been restructured to follow the Diataxisframework, dividing content into into learning-, task-, understanding- and information-oriented sections.

I think people may be missing the core point of this article.

Anton has built a new thing, https://codapi.org/ - which provides a web component that makes it easy to embed interactive code snippets for HTTP APIs, Python code and more directly in pages of documentation.

This article demonstrates this new technology in the context of the https://diataxis.fr/ documentation framework, which recommends going beyond just straight API reference documentation and ensuring you cover tutorials, how-to guides and explanations as well.

I think this is really cool.

As much as possible on all facets, because that is what "documentation" means, and if you are a product manager who wasn't paying attention in product management 101 and need some guidance on what "documentation" is, try reading this first.

Related: Diátaxis - A systematic framework for technical documentation authoring [1]

"The Diátaxis framework aims to solve the problem of structure in technical documentation. It adopts a systematic approach to understanding the needs of documentation users in their cycle of interaction with a product.

Diátaxis identifies four modes of documentation - tutorials, how-to guides, technical reference and explanation. It derives its structure from the relationship between them.(...)"

[1] https://diataxis.fr/

the divio style docs concept got further refined by the creator with this - https://diataxis.fr/

mostly the same but some additional information for people who are interested