Remove all duplicate content - #193
Conversation
Users should read the Learn documentation for programming info.
There was a problem hiding this comment.
Pull request overview
This PR simplifies the repository’s README by removing the large in-repo “how to use the SDK” content, shifting readers toward Microsoft Learn documentation for programming guidance.
Changes:
- Replaces the long-form README usage/feature documentation with a short introductory description and link hub.
- Removes extensive examples and “getting started” sections from the README.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| The Dataverse SDK for Python enables Python developers to interact directly with Microsoft Dataverse. You can easily access, manage, and manipulate data stored in Dataverse by using familiar Python syntax. You don't need any .NET knowledge. The Python client library for Microsoft Dataverse provides a unified interface for CRUD (create, retrieve, update, delete) operations, SQL queries, table customization, and file uploads through the Dataverse Web API. | ||
|
|
||
| **[Source code](https://github.com/microsoft/PowerPlatform-DataverseClient-Python)** | **[Package (PyPI)](https://pypi.org/project/PowerPlatform-Dataverse-Client/)** | **[API reference documentation](https://learn.microsoft.com/python/api/dataverse-sdk-docs-python/dataverse-overview?view=dataverse-sdk-python-latest)** | **[Product documentation](https://learn.microsoft.com/power-apps/developer/data-platform/sdk-python/)** | **[Samples](https://github.com/microsoft/PowerPlatform-DataverseClient-Python/tree/main/examples)** | ||
|
|
Suyash Kshirsagar (suyask-msft)
left a comment
Suyash Kshirsagar (suyask-msft)
left a comment
There was a problem hiding this comment.
I dug into how Microsoft's own Azure SDKs and other industry SDKs (Stripe, Twilio, boto3, google-cloud) split this, and I don't think "Learn = single source" should mean "everything moves to Learn." The winning pattern everywhere is single-source per content type, not one location for everything. Here's what I'd propose:
The model that works (this is literally what Azure SDK for Python does):
- README (GitHub + PyPI) = a self-contained quickstart. It's the first thing every dev sees on PyPI and in the repo, so it must stand alone: install, authenticate, key concepts, 5–8 common code snippets, troubleshooting basics, and a link bar to the deeper docs. It is authored once in the repo and PyPI just mirrors it — that's already how we do it, and we should keep it.
- Microsoft Learn = the system of record for depth: conceptual guides, task-based How-Tos (work with data, query, metadata, relationships, async), and the auto-generated API reference. This is where "single source of truth" genuinely applies — anything conceptual or exhaustive lives here, not duplicated in the README.
- The link bar at the top of the README (Source | PyPI | API reference | Product docs | Samples) is the bridge. We already have it.
What I'd actually change: our README is ~1,150 lines / 50 KB — the comparable Azure SDK README (azure-storage-blob) is ~460 lines / 24 KB. We've let deep how-to material (full relationship metadata, batch changesets, DataFrame recipes, timeout tuning) pile into the README that really belongs in Learn How-Tos. So the meeting outcome shouldn't be "copy README into Learn"; it should be "move the deep material to Learn, slim the README to a quickstart, and deep-link." One authoritative home per topic, zero duplication.
The split (bring this table)
Content | README (repo → PyPI) | Microsoft Learn -- | -- | -- Install + prerequisites | ✅ Full | Short pointer Authenticate (the 2–3 common credentials) | ✅ Full | ✅ Deep (all credential types, app reg, OAuth setup) Key concepts (client, namespaces, records) | ✅ Short | ✅ Conceptual depth Common code snippets (CRUD, quick query, bulk) | ✅ 5–8 curated | — Task How-Tos (query, metadata, relationships, async, batch, DataFrame) | Brief snippet + deep link | ✅ Authoritative API reference (classes/methods/params) | Link only | ✅ Authoritative (auto-generated) Troubleshooting (exception hierarchy, timeouts, logging) | ✅ Essentials | ✅ Extended Contributing / CLA / trademarks | ✅ | —
Users should read the Learn documentation for programming info.