Am I the only one who finds the documentation good on concepts but poor on examples?

> You invest years learning their stack, so the friction cost of switching seems higher than the weekend you'll waste on their incomplete docs.

This is precisely the vendor lock-in calculus, and it's often most damaging in the data warehouse space. You see teams adopt a platform like BigQuery or Snowflake for its conceptual promise of infinite scale and separation of compute/storage. They build years of complex transformation logic, modeling patterns, and pipeline orchestration on that stack.

Then, when you hit a hard limit in their implementation - say, the undocumented, non-standard SQL behavior for `MERGE` with streaming data, or the exact parameters needed for a cost-control policy - you're faced with that exact cost-benefit analysis. Rewriting years of pipeline logic for another vendor seems astronomically more expensive than the collective weeks you'll spend spelunking through network calls and forum posts for the correct syntax. The vendor wins by making the *correct* documentation just scarce enough that the switching cost always feels prohibitive.

The reverse-engineering step you described, pulling the real schema from a network call, is the unspoken best practice for so many of these platforms now. It's become a de facto part of the integration process.

Your missing `type` field is a classic symptom. I've hit the same wall not with Elastic, but with chatbot platforms when trying to define custom entity recognition rules. The conceptual docs preach precision and flexibility, but the actual JSON to exclude an entity in a specific dialog state requires a `matchMode` property that only appears in the UI's POST payload. You find it by watching the browser console, not by reading the API reference.

It feels less like poor documentation and more like the examples are a separate, depreciated product line they forgot to cancel.

That "hidden engineering tax" is a great way to put it. I'm new to this kind of evaluation, but it makes me wonder about cost planning. When you're comparing SaaS tools, how do you even factor that in? The weekend you mention isn't on the pricing page, but it's a real cost.

So when you said they sell the vision first, is the takeaway that you should assume the examples are incomplete, and just budget for that detective work from the start? It sounds like it's less about finding a platform with perfect docs and more about expecting to reverse-engineer.

You're hitting on the hardest part of vendor selection. That weekend of detective work is absolutely a line item, but you can't quantify it upfront.

My rule is to check the community forum and GitHub issues *before* signing a contract. I look for two things: the volume of "how do I..." questions, and more importantly, if the staff replies link to the official docs or post their own working snippets. If it's the latter, you've found your tax rate. It tells you the internal team doesn't trust the published examples either.

So yes, budget for reverse-engineering. But also budget for maintenance, because those hidden fields you find in the network tab today can change with a UI update tomorrow, and that won't be in the changelog.