Missing/Misleading async usage examples for long-running operations in Python SDK documentation caused production issues

### Type of issue

Missing information

### Description

The [Azure AI Document Intelligence Python SDK documentation](https://learn.microsoft.com/en-us/python/api/overview/azure/ai-documentintelligence-readme?view=azure-python#examples) explicitly states that long-running operations (e.g., analyze documents, build models) return LROPoller or AsyncLROPoller and that async usage is supported. The Prerequisites section even mentions installing aiohttp for async transport.

However — not a single sample in the Examples section demonstrates how to use the asynchronous client or AsyncLROPoller. Every example is synchronous and uses poller.result(), which blocks execution until the operation completes.

This omission is not a small gap in docs — it directly impacted my production workload:

I was running high-load, long-running document analysis at scale.

I followed the provided examples, assuming this was the intended usage pattern.

Because no async example existed, I implemented it synchronously.

Under production load, synchronous blocking calls severely limited concurrency, caused unnecessary resource exhaustion, and led to throughput collapse during peaks.

Only after digging into the SDK source and other Azure SDK patterns did I discover that async usage is not just supported — it is essential for high-throughput, non-blocking processing of LROs.

Why this is critical:

Async usage is not optional for many real-world workloads — especially with long-running operations under high concurrency.

Azure Document Intelligence supports auto-scaling, meaning the service can handle many concurrent requests — but the provided sync-only examples make it easy for developers to create a client bottleneck that negates those scaling benefits.

The lack of async samples misleads developers into adopting blocking patterns that are incompatible with large-scale production scenarios.

### Page URL

https://learn.microsoft.com/en-us/python/api/overview/azure/ai-documentintelligence-readme?view=azure-python#long-running-operations

### Content source URL

https://github.com/MicrosoftDocs/azure-docs-sdk-python/blob/main/docs-ref-services/latest/ai-documentintelligence-readme.md

### Document Version Independent Id

be033072-fc7b-832b-eb4e-475685478e43

### Platform Id

dca95708-121d-d4c4-e911-f8f7fdbfae80

### Article author

@azure-sdk

### Metadata

* ID: b0532276-a194-de5c-e0ca-2ec9bd95f092
* PlatformId: dca95708-121d-d4c4-e911-f8f7fdbfae80
* Service: **documentintelligence**